baldart 5.2.0 → 5.2.1

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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).
 
+## [5.2.1] - 2026-07-03
+
+**`/mw` local-trunk sync robustness.** The worktree merge's local-trunk sync
+(step 4c "Common", both `pr` and `local-push` strategies) failed to
+fast-forward on the majority of real checkouts, needlessly leaving
+`SYNC-DEFERRED` / `SYNC-NEEDS-DECISION`. Two targeted fixes, kept single-sourced
+across the executed SSOT (`framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh`)
+and the prose (`worktree-manager/SKILL.md` step 4c) — **without `git stash`**,
+which stays forbidden here because `refs/stash` is shared across all worktrees
+via `git.commondir` (the FEAT-0522 incident): a stash from the main checkout can
+pop into the wrong worktree, and two parallel `/mw` runs race on the shared
+stash list.
+
+- **Fix 1 — safe ref-advance when main is on another branch.** Previously, if
+  the main repo's HEAD was not on `$TRUNK`, sync did a fetch-only and always
+  emitted `SYNC-DEFERRED`, never advancing the local `$TRUNK` ref. Now it
+  fast-forwards `refs/heads/$TRUNK` via a ref-only, ff-only fetch
+  (`git fetch origin $TRUNK:$TRUNK`) that **never touches any working tree** and
+  never checks out — turning a large class of deferrals into a clean sync
+  (`sync_marker: none`). If `$TRUNK` is checked out in another worktree, git
+  refuses and it falls back to fetch-only + defer.
+- **Fix 2 — accurate ff-fail disambiguation.** When the ff failed with a
+  tracked-clean tree and no owned/foreign dirt, the code fell to a misleading
+  "clean (diverged?)" marker (the dirty scan uses `--untracked-files=no`, so an
+  untracked-file collision was invisible to it). Now it disambiguates via
+  `merge-base --is-ancestor` between a **genuine branch divergence** (needs a
+  rebase/merge decision) and an **untracked-file collision** (the blocking files
+  are enumerated), emitting the correct actionable marker.
+
+Behaviour is strictly safer: cases #2 (foreign uncommitted work) and #3 (real
+divergence) still defer to ONE explicit user gate — never auto-committed, never
+stashed — which is the correct behaviour on a shared checkout.
+
+**Codex parity: portable.** The change is pure git plumbing inside the
+dual-runtime `merge-worktree.sh` (executed identically under Claude and Codex)
+plus its prose twin; no runtime-specific mechanic, no config key. The
+schema-change propagation rule does not apply (no `baldart.config.yml` key).
+
 ## [5.2.0] - 2026-07-03
 
 **The local design studio.** `/ui-design` is refounded from the root as the

package/VERSION

@@ -1 +1 @@
-5.2.0
+5.2.1

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

@@ -2,6 +2,25 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.0 — 2026-07-03
+
+### Fixed — local-trunk sync robustness (step 4c "Common", both strategies)
+
+Il sync del trunk locale falliva l'ff nella maggior parte dei checkout reali,
+lasciando `SYNC-DEFERRED` / `SYNC-NEEDS-DECISION` inutilmente. Due fix mirati,
+**senza `git stash`** (vietato — `refs/stash` è condiviso tra worktree, incidente
+FEAT-0522). SSOT script `scripts/merge-worktree.sh` + prose SKILL.md tenuti in sync.
+
+- **Fix 1** — quando il main è su un branch ≠ `$TRUNK`, avanza il *ref* locale
+  `refs/heads/$TRUNK` con un fetch ref-only ff-only (`git fetch origin $TRUNK:$TRUNK`),
+  **senza toccare il working tree** e senza checkout. Converte una grossa fetta di
+  `SYNC-DEFERRED` in sync pulito (`sync_marker: none`). Se `$TRUNK` è checked out in
+  un altro worktree git rifiuta → fallback al fetch-only + defer.
+- **Fix 2** — quando l'ff fallisce con tree tracked-clean e nessun file owned/foreign,
+  disambigua via `merge-base --is-ancestor` tra **divergenza reale** del branch (serve
+  rebase/merge) e **collisione con file untracked** (elencati) — prima riportava sempre
+  il fuorviante "clean (diverged?)" (lo scan usa `--untracked-files=no`).
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,7 @@
 ---
 name: worktree-manager
 effort: medium
-version: 1.0.0
+version: 1.1.0
 description: >
   Manage fully independent git worktrees for parallel coding agents.
   Commands: /nw (new worktree) creates an isolated workspace with its own
@@ -1168,16 +1168,37 @@ if [ "$CURRENT_BRANCH" = "$TRUNK" ]; then
         echo "[SYNC-NEEDS-DECISION] framework-managed reconcile rebase conflict on $TRUNK — orchestrator MUST raise ONE explicit user gate."
       fi
     else
-      echo "[SYNC-NEEDS-DECISION] main repo $TRUNK cannot fast-forward and the working tree is clean (diverged?) — orchestrator MUST raise ONE explicit user gate."
+      # Fix 2 — tracked tree clean, nothing owned/foreign dirty, yet ff failed.
+      # Disambiguate a genuine branch divergence from an untracked-file collision the
+      # incoming ff would overwrite (origin/$TRUNK is current — the pull fetched it).
+      # NEVER stash to clear it (refs/stash is shared across worktrees — FEAT-0522).
+      if git -C "$MAIN" merge-base --is-ancestor "$TRUNK" "origin/$TRUNK" 2>/dev/null; then
+        COLLIDE=""
+        for f in $(git -C "$MAIN" ls-files --others --exclude-standard); do
+          git -C "$MAIN" cat-file -e "origin/$TRUNK:$f" 2>/dev/null && COLLIDE="$COLLIDE $f"
+        done
+        echo "[SYNC-NEEDS-DECISION] main repo $TRUNK is fast-forwardable but untracked file(s) block the merge:${COLLIDE:- (unknown)} — orchestrator MUST raise ONE explicit user gate."
+      else
+        echo "[SYNC-NEEDS-DECISION] main repo $TRUNK has diverged from origin/$TRUNK (local commits not on origin) — needs a rebase/merge decision; orchestrator MUST raise ONE explicit user gate."
+      fi
     fi
   fi
 else
-  echo "ℹ️ Main repo HEAD is '$CURRENT_BRANCH' — not switching. Next manual \`git pull\` on $TRUNK will sync."
-  git -C "$MAIN" fetch origin "$TRUNK" --quiet
-  # Structured marker for upstream orchestrators (e.g. /new Phase 6c).
-  # `/mw` standalone keeps fetch-only behavior (terminal isolation); orchestrators
-  # parse this marker and route reconciliation through an explicit user gate.
-  echo "[SYNC-DEFERRED] main repo HEAD=${CURRENT_BRANCH}, local $TRUNK not fast-forwarded — orchestrator workspace-hygiene phase must reconcile."
+  # Fix 1 — main is on another branch: do NOT checkout $TRUNK. Fast-forward the local
+  # $TRUNK *ref* without touching any working tree via a ref-only, ff-only fetch.
+  # `git fetch origin $TRUNK:$TRUNK` advances refs/heads/$TRUNK only on a fast-forward
+  # and fails cleanly otherwise (never a checkout, never a stash). If $TRUNK is checked
+  # out in another worktree git refuses → we fall back to fetch-only + defer.
+  if git -C "$MAIN" fetch origin "$TRUNK:$TRUNK" --quiet 2>/dev/null; then
+    echo "✅ Local $TRUNK ref fast-forwarded to origin/$TRUNK (main HEAD='$CURRENT_BRANCH' untouched)."
+  else
+    echo "ℹ️ Main repo HEAD is '$CURRENT_BRANCH' — not switching. Next manual \`git pull\` on $TRUNK will sync."
+    git -C "$MAIN" fetch origin "$TRUNK" --quiet
+    # Structured marker for upstream orchestrators (e.g. /new Phase 6c).
+    # `/mw` standalone keeps fetch-only behavior (terminal isolation); orchestrators
+    # parse this marker and route reconciliation through an explicit user gate.
+    echo "[SYNC-DEFERRED] main repo HEAD=${CURRENT_BRANCH}, local $TRUNK not fast-forwarded (diverged or checked out elsewhere) — orchestrator workspace-hygiene phase must reconcile."
+  fi
 fi
 ```
 

package/framework/.claude/skills/worktree-manager/scripts/merge-worktree.sh

@@ -492,12 +492,34 @@ if [ "$CURRENT_BRANCH" = "$TRUNK" ]; then
         M_SYNCMARK="SYNC-NEEDS-DECISION"; M_SYNCDETAIL="framework-managed reconcile rebase conflict on $TRUNK"
       fi
     else
-      M_SYNCMARK="SYNC-NEEDS-DECISION"; M_SYNCDETAIL="main repo $TRUNK cannot fast-forward and the working tree is clean (diverged?)"
+      # Fix 2 — tracked tree clean, nothing owned/foreign dirty, yet ff failed.
+      # Disambiguate a genuine branch divergence from an untracked-file collision
+      # the incoming ff would overwrite (origin/$TRUNK is current — pull fetched it).
+      # NEVER stash to clear it (refs/stash is shared across worktrees — FEAT-0522).
+      if git -C "$MAIN" merge-base --is-ancestor "$TRUNK" "origin/$TRUNK" 2>/dev/null; then
+        COLLIDE=""
+        for f in $(git -C "$MAIN" ls-files --others --exclude-standard 2>/dev/null); do
+          git -C "$MAIN" cat-file -e "origin/$TRUNK:$f" 2>/dev/null && COLLIDE="$COLLIDE $f"
+        done
+        M_SYNCMARK="SYNC-NEEDS-DECISION"; M_SYNCDETAIL="main repo $TRUNK is fast-forwardable but untracked file(s) block the merge:${COLLIDE:- (unknown)} — orchestrator MUST raise ONE explicit user gate"
+      else
+        M_SYNCMARK="SYNC-NEEDS-DECISION"; M_SYNCDETAIL="main repo $TRUNK has diverged from origin/$TRUNK (local commits not on origin) — needs a rebase/merge decision, orchestrator MUST raise ONE explicit user gate"
+      fi
     fi
   fi
 else
-  git -C "$MAIN" fetch origin "$TRUNK" --quiet 2>>"$LOG" || true
-  M_SYNCMARK="SYNC-DEFERRED"; M_SYNCDETAIL="main repo HEAD=${CURRENT_BRANCH}, local $TRUNK not fast-forwarded"
+  # Fix 1 — main is on another branch: do NOT checkout $TRUNK. Fast-forward the local
+  # $TRUNK *ref* (refs/heads/$TRUNK) WITHOUT touching any working tree via a ref-only,
+  # ff-only fetch. `git fetch origin $TRUNK:$TRUNK` advances the local branch ref only
+  # on a fast-forward and fails cleanly (non-destructive) otherwise — never a checkout,
+  # never a stash. If $TRUNK is checked out in another worktree git refuses and we fall
+  # back to the deferred fetch below.
+  if git -C "$MAIN" fetch origin "$TRUNK:$TRUNK" --quiet 2>>"$LOG"; then
+    M_SYNCMARK="none"; M_SYNCDETAIL="local $TRUNK ref fast-forwarded to origin (main HEAD=${CURRENT_BRANCH}, working tree untouched)"
+  else
+    git -C "$MAIN" fetch origin "$TRUNK" --quiet 2>>"$LOG" || true
+    M_SYNCMARK="SYNC-DEFERRED"; M_SYNCDETAIL="main repo HEAD=${CURRENT_BRANCH}, local $TRUNK not fast-forwarded (diverged or checked out elsewhere)"
+  fi
 fi
 
 # 7. Cleanup worktree + registry (only after a verified land). Individual cmds.

package/package.json

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