baldart 3.38.0 → 3.39.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.39.0] - 2026-06-01
+
+**A `/prd` or `/new` run now CONCLUDES clean — it never ends by handing the user a list of "azioni tue, non bloccanti" (an uncommitted file blocking the local `develop` fast-forward, a merged remote branch left undeleted).** Every workspace-hygiene leftover is either auto-resolved by the finalizer or put behind ONE explicit `AskUserQuestion` gate. No passive manual TODO ever survives into the final summary. **No new `baldart.config.yml` keys.**
+
+> **Why.** A `/prd` finalization closed with: *"il develop locale non si è fast-forwardato per una modifica non committata pre-esistente a `docs/metrics/skill-runs.jsonl` — gestisci quel file e poi `git pull --ff-only`"* and *"il branch remoto non è stato eliminato — puoi cancellarlo a mano"*. The orchestrator declared the run "completato" while leaving the workspace half-finished. Root cause: `worktree-manager mw-docs` printed `⚠️ … Leaving as-is` on a blocked fast-forward, and `/prd` (unlike `/new` Phase 6c) had no workspace-hygiene phase to consume that — it forwarded the warning to the user verbatim.
+
+### Changed — the merge finalizer auto-resolves instead of giving up
+
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)** (Common — sync local develop): the blocked-ff path no longer prints `Leaving as-is`. It partitions the dirty tree: the framework-owned append-only telemetry log (`docs/metrics/skill-runs.jsonl`) is reconciled autonomously and losslessly (commit + `pull --rebase` + best-effort push) so the ff completes; ANY foreign file emits a new `[SYNC-NEEDS-DECISION]` marker the orchestrator MUST convert into one explicit gate. Work this run does not own is never auto-committed.
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)** (Cleanup step 6.3 + report): merged remote-branch deletion is now an explicit, reported step (was `2>/dev/null || true` silent) — a denial is retried, never degraded into a "puoi cancellarlo a mano" note.
+
+### Added — `/prd` Step 7.5 Workspace Hygiene & finalization (BLOCKING)
+
+- **[framework/.claude/skills/prd/references/validation-phase.md](framework/.claude/skills/prd/references/validation-phase.md)**: new Step 7.5 mirrors `/new` Phase 6c — consumes the `[SYNC-NEEDS-DECISION]` / `[SYNC-DEFERRED]` markers, raises ONE `AskUserQuestion` per unresolved residue, ensures the merged remote branch is gone. New **HARD RULE** in Final output: the summary MUST NOT contain a "azioni tue / note non bloccanti" section — a run that prints "gestisci tu il file e poi pulla" has FAILED Step 7.5.
+
+### Changed — `/new` Phase 6c parses the new marker
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md)** (Phase 6c step 2): now also parses `[SYNC-NEEDS-DECISION]` (foreign-file ff block / rebase conflict) as a blocking gate, alongside the existing `[SYNC-DEFERRED]`.
+
+### Changed — AGENTS.md scopes branch-deletion approval to unmerged branches
+
+- **[framework/AGENTS.md](framework/AGENTS.md)**: owner approval is required before deleting an **unmerged** branch; deleting an **already-merged** feature branch is routine cleanup the merge skill performs automatically (no separate approval). The "prune remote branches only when instructed" rule is clarified to exclude a feature branch's own ref on successful merge.
+
+### Revert
+
+- Restore the `git -C "$MAIN" pull --ff-only origin develop || echo "⚠️ … Leaving as-is."` one-liner in `worktree-manager` and drop `/prd` Step 7.5.
+
 ## [3.38.0] - 2026-06-01
 
 **The per-card review depth (QA + Codex) is now decided deterministically in the backlog card via a new `review_profile` field, computed once at PRD authoring time — instead of being re-derived heuristically by `/new` at runtime.** This removes the implementing agent's interpretation latitude: the card carries `skip|light|balanced|deep`, `/new` READS it, and only falls back to runtime computation for legacy cards that predate the field. **No new `baldart.config.yml` keys** — this is a backlog-card schema change, propagated end-to-end across templates + card-writer + validation + `/new` in the same release.

package/VERSION

@@ -1 +1 @@
-3.38.0
+3.39.0

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

@@ -1745,9 +1745,14 @@ The most common failure mode is leaving cards IN_PROGRESS after merge. This crea
    git -C "$MAIN" fetch origin --quiet
    ```
 
-2. **Parse `[SYNC-DEFERRED]` markers** — scan the captured stdout from every `/mw` invocation in this batch (kept in the tracker under `## Worktree Merges`) for `[SYNC-DEFERRED] main repo HEAD=<branch>` lines. If present, surface to the user via `AskUserQuestion`:
-   - Question: `"Una o più merge worktree hanno deferito la sincronizzazione di local develop (main repo HEAD non era develop). Come riconcilio adesso?"`
-   - Options: `[Ora HEAD è develop → ff-pull adesso]` / `[Lascia deferred (riconcilio io manualmente)]` / `[Mostra dettagli e fammi decidere]`.
+2. **Parse `mw-docs` sync markers** — scan the captured stdout from every `/mw` invocation in this batch (kept in the tracker under `## Worktree Merges`):
+   - **`[SYNC-DEFERRED] main repo HEAD=<branch>`** (main repo HEAD ≠ develop) — surface via `AskUserQuestion`:
+     - Question: `"Una o più merge worktree hanno deferito la sincronizzazione di local develop (main repo HEAD non era develop). Come riconcilio adesso?"`
+     - Options: `[Ora HEAD è develop → ff-pull adesso]` / `[Lascia deferred (riconcilio io manualmente)]` / `[Mostra dettagli e fammi decidere]`.
+   - **`[SYNC-NEEDS-DECISION] …`** (HEAD was develop but the ff was blocked by a **foreign** uncommitted file, or by a divergence/rebase conflict `/mw` would not auto-commit) — this is NEVER a passive note. Surface via `AskUserQuestion`:
+     - Question: `"Il develop locale non si è sincronizzato: <dettaglio dal marker>. Come chiudo?"`
+     - Options: `[Committa tu adesso (descrivi cosa)]` / `[Lo gestisco io — chiudi senza sync locale]` / `[Mostrami il diff e decidiamo]`.
+   - **No marker** — `/mw` fast-forwarded (or auto-reconciled the framework telemetry log); nothing to parse.
 
 3. **Clean-tree assertion (BLOCKING)**:
    ```bash

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -184,6 +184,45 @@ the state file (now on `develop` via the merge) shows `completed`.
 
 Mark task 5 as `completed`.
 
+### Step 7.5 — Workspace hygiene & finalization (BLOCKING — the run MUST conclude clean)
+
+**Why this exists (v3.39.0).** A PRD run used to end by handing the user a list of
+"azioni tue, non bloccanti" — an uncommitted file blocking the local `develop`
+fast-forward, a remote branch left undeleted. That is a half-finished process.
+`/prd` now closes the loop exactly like `/new` Phase 6c: **no residue is ever
+surfaced as a passive manual TODO.** Every leftover is either auto-resolved or put
+behind ONE explicit `AskUserQuestion` gate.
+
+Scan the captured `mw-docs` stdout (the merge step above) for the structured
+markers it can emit, then act:
+
+1. **`[SYNC-NEEDS-DECISION] …`** — the local `develop` could not fast-forward and
+   the blocker is a **foreign** uncommitted file (one this run does not own), or a
+   genuine divergence/rebase conflict. Do NOT auto-commit foreign work. Raise ONE
+   `AskUserQuestion`:
+   - Question: `"Il develop locale non si è sincronizzato: <dettaglio dal marker>. Come chiudo?"`
+   - Options: `[Committa tu adesso (descrivi cosa)]` / `[Lo gestisco io — chiudi senza sync locale]` / `[Mostrami il diff e decidiamo]`.
+   Act on the answer in this turn. Never leave it as a printed note.
+
+2. **`[SYNC-DEFERRED] …`** (main repo HEAD ≠ `develop`) — fetch already updated
+   `refs/remotes/origin/develop`. If the user's HEAD is now `develop`, run
+   `git -C "$MAIN" pull --ff-only origin develop`. Otherwise raise ONE
+   `AskUserQuestion` (`[ff-pull adesso]` / `[Lascio deferred, riconcilio io]`).
+
+3. **No marker** — `mw-docs` already fast-forwarded (or auto-reconciled the
+   framework telemetry log). Nothing to do; the tree is clean.
+
+4. **Remote feature branch** — `mw-docs` deletes the merged remote branch as
+   routine cleanup (see AGENTS.md § branch deletion: deleting an **already-merged**
+   feature branch is NOT the gated "branch deletion" that needs owner approval).
+   If for any reason the deletion was blocked, do NOT print "puoi cancellarlo a
+   mano": run `git push origin --delete <branch>` now, and only if THAT is denied
+   raise ONE `AskUserQuestion`.
+
+**Gate:** `git -C "$MAIN" status --porcelain` for framework-owned paths is empty,
+no `[SYNC-NEEDS-DECISION]` marker is left unhandled, and the merged remote branch
+is gone (or its deletion is explicitly user-deferred).
+
 ### Final output
 
 Print final summary:
@@ -193,6 +232,13 @@ Print final summary:
 - Card IDs created
 - Branch & merge strategy used
 - PR number (if `strategy = pr`) or merge SHA (if `local-push`)
-- Confirmation that the worktree was cleaned up
+- Confirmation that the worktree was cleaned up AND the remote branch was deleted
+
+**HARD RULE — no passive deferral.** The final summary MUST NOT contain a "azioni
+tue / note non bloccanti / puoi farlo a mano" section. If something genuinely needs
+the user, it was already raised as an `AskUserQuestion` in Step 7.5 and acted on —
+it does not reappear here as a TODO. A run that prints "il develop locale non si è
+fast-forwardato, gestisci tu il file e poi pulla" has FAILED Step 7.5 — go back and
+resolve it before printing the summary.
 
 Display completed Progress Bar.

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

@@ -865,8 +865,44 @@ PR_NUMBER=""
 # 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 || \
-    echo "⚠️ Could not fast-forward main repo develop (uncommitted work?). Leaving as-is."
+  if git -C "$MAIN" pull --ff-only origin develop 2>/dev/null; then
+    echo "✅ Main repo develop fast-forwarded to origin/develop."
+  else
+    # FF blocked. NEVER leave this as a passive "Leaving as-is" TODO for the user
+    # (v3.39.0 — the finalizer MUST conclude). The cause is almost always an
+    # uncommitted append to the framework-owned telemetry log left by a prior run.
+    # Partition the dirty tree:
+    #   - framework-owned artifact (docs/metrics/skill-runs.jsonl) → auto-reconcile
+    #     (commit + rebase) so the ff completes with zero data loss;
+    #   - ANY foreign file → emit a decision marker the orchestrator MUST convert
+    #     into ONE explicit user gate. Never auto-commit work this run did not own.
+    DIRTY=$(git -C "$MAIN" status --porcelain --untracked-files=no | sed 's/^...//')
+    FOREIGN=""
+    OWNED=""
+    for f in $DIRTY; do
+      case "$f" in
+        docs/metrics/skill-runs.jsonl) OWNED="$OWNED $f" ;;
+        *) FOREIGN="$FOREIGN $f" ;;
+      esac
+    done
+    if [ -n "$FOREIGN" ]; then
+      echo "[SYNC-NEEDS-DECISION] main repo develop cannot fast-forward; foreign uncommitted files:${FOREIGN} — orchestrator MUST raise ONE explicit user gate (commit / user-handles), never a passive note."
+    elif [ -n "$OWNED" ]; then
+      # Only framework-owned telemetry is dirty → reconcile autonomously, lossless.
+      git -C "$MAIN" add docs/metrics/skill-runs.jsonl
+      git -C "$MAIN" commit -m "chore(metrics): reconcile skill-runs telemetry before develop sync" --quiet
+      if git -C "$MAIN" pull --rebase origin develop 2>/dev/null; then
+        git -C "$MAIN" push origin develop 2>/dev/null \
+          && echo "✅ Reconciled stale metrics log + synced develop to origin." \
+          || echo "✅ Reconciled stale metrics log (local develop 1 commit ahead; syncs on next push). Tree clean."
+      else
+        git -C "$MAIN" rebase --abort 2>/dev/null || true
+        echo "[SYNC-NEEDS-DECISION] metrics rebase conflict on develop — orchestrator MUST raise ONE explicit user gate."
+      fi
+    else
+      echo "[SYNC-NEEDS-DECISION] main repo develop cannot fast-forward and the working tree is clean (diverged?) — orchestrator MUST raise ONE explicit user gate."
+    fi
+  fi
 else
   echo "ℹ️ Main repo HEAD is '$CURRENT_BRANCH' — not switching. Next manual `git pull` on develop will sync."
   git -C "$MAIN" fetch origin develop --quiet
@@ -905,8 +941,17 @@ git branch -d "$BRANCH"
 ```
 
 ```bash
-# 3. Delete the remote branch (optional — may not exist if never pushed)
-git push origin --delete "$BRANCH" 2>/dev/null || true
+# 3. Delete the remote branch. The branch is ALREADY MERGED into develop at this
+#    point, so this is routine cleanup — NOT the gated "branch deletion" that needs
+#    owner approval (see AGENTS.md § branch deletion). Report the outcome; never
+#    degrade a failure into a passive "puoi cancellarlo a mano" note handed to the user.
+if git push origin --delete "$BRANCH" 2>/dev/null; then
+  echo "✅ Remote branch '$BRANCH' deleted (merged → routine cleanup)."
+else
+  echo "ℹ️ Remote branch '$BRANCH' not deleted (already gone, or the deletion was denied)."
+  echo "   If denied: this is a merged branch — retry the delete; only if it is STILL"
+  echo "   denied must the orchestrator raise ONE explicit user gate, never a passive TODO."
+fi
 ```
 
 ```bash
@@ -923,12 +968,15 @@ 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)
+  Branch:   <BRANCH> (deleted on remote — merged branch deletion is routine cleanup, never gated)
   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
+  develop:  remote up to date; local main-repo synced (auto-reconciled framework
+            telemetry if it blocked the ff). Any [SYNC-NEEDS-DECISION] /
+            [SYNC-DEFERRED] marker above is for the orchestrator to gate on —
+            NOT a residue to hand the user as a manual TODO.
 ```
 
 ---

package/framework/AGENTS.md

@@ -104,9 +104,9 @@ Conflict steps (must follow in order):
 - MUST use commit format `[FEAT-XXX] Brief description` or adapt to your project's convention; keep commits small/traceable.
 - MUST NOT commit without updated docs or with failing lint/type checks. Full build is required only before opening a PR, not before every commit.
 - MUST pre-sync: `git fetch origin`, clean status, confirm branch; use `git pull --ff-only` unless approved.
-- MUST get owner approval before force push/reset/branch deletion; create a safety tag `backup/<YYYYMMDD>-<reason>`.
+- MUST get owner approval before force push/reset, and before deleting an **unmerged** branch; create a safety tag `backup/<YYYYMMDD>-<reason>`. Deleting a feature branch that is **already merged** into `develop` is routine cleanup (it carries no unmerged work) and does NOT require a separate approval — the merge skill deletes it automatically.
 - MUST NEVER push directly to `main`; all changes reach `main` via PR (release from `develop` or hotfix merge). Pre-push hook enforces this.
-- MUST push working branch and keep `main` merge owner-controlled; prune remote branches only when instructed.
+- MUST push working branch and keep `main` merge owner-controlled; the merge skill prunes a feature branch's own remote ref on successful merge into `develop` (routine), but pruning OTHER remote branches happens only when instructed.
 - MUST run testing gates before DONE: run tests (if exist), run build, and CI checks on PR; manual validation is REQUIRED for local mode and OPTIONAL for cloud mode.
 - MUST pass pre-commit hooks (linting, type checking, markdown lint, build); bypass (`--no-verify`) only for documented emergencies.
 - MUST use API versioning for breaking changes: create new version, deprecate old with appropriate headers, minimum sunset period; see project-specific API migration docs.

package/package.json

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