baldart 4.1.0 → 4.1.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.1.1] - 2026-06-02
+
+**Fix: `/prd` (and `/new`) silently stopped creating their worktree after updating to ≥4.0.0.** Regression introduced in v4.0.0: `worktree-manager` was rewritten to resolve the worktree base from the **new `git.trunk_branch` config key** and to **hard-`exit 1`** when it is absent ("never assume develop"). Because `baldart update` never overwrites `baldart.config.yml`, every consumer that updated without re-running `configure` had no `git.trunk_branch` → the `nw-docs` / `nw` pre-flight aborted → no worktree. v4.0.0 also downgraded the `/prd` Step 1 worktree gate from BLOCKING to a non-blocking "MONITORING SIGNAL", so the abort no longer surfaced as a hard STOP — the session drifted into Discovery on the main checkout instead. **PATCH** (regression fix, no new capability, no schema change).
+
+> **Why.** Before v4.0.0 the worktree base was hardcoded `origin/develop`, so creation always worked. Making it config-driven was correct, but the missing-key path should degrade to autodetection, not a hard failure — and the safety gate that would have caught the failure was removed in the same release. The fix resolves the trunk the same way `configure.js` already does (`origin/HEAD` → local `develop`/`main`/`master`), which is *not* "assume develop": it resolves the branch the repo actually uses.
+
+### Fixed
+
+- **`worktree-manager` `nw-docs` + `nw` pre-flight** — when `git.trunk_branch` is absent from `baldart.config.yml`, autodetect the real default branch (`git symbolic-ref refs/remotes/origin/HEAD` → first existing local `develop`/`main`/`master`) and warn, instead of `exit 1`. Hard-abort only when even autodetection finds nothing (bare repo / no branches). This unblocks `/prd` and `/new` worktree creation on consumers that updated without re-running `configure`.
+- **`/prd` Step 1 worktree gate** (`prd/references/discovery-phase.md`) — restored from "MONITORING SIGNAL (non-blocking)" back to a **BLOCKING gate**: the kickoff "Ho creato la sessione PRD … in un worktree dedicato" message is emitted only after the worktree is verified on disk; if `nw-docs` aborted, HALT and surface the error verbatim instead of proceeding to Discovery on the main checkout (HARD RULE 17).
+- **`/new` Phase 0 trunk resolution** (`new/SKILL.md`) — when `git.trunk_branch` is absent, `/new` now autodetects the trunk with the **same** `origin/HEAD` → `develop`/`main`/`master` logic as `worktree-manager`, instead of hard-assuming the `develop` literal. Keeps `/new`'s `$TRUNK` (used by the divergence gate and every `git diff "$TRUNK...HEAD"` gate) in lockstep with the branch `nw` actually bases the worktree on — a `main`-trunk repo no longer diverges between the two.
+- **`update.js` schema-drift notice** — when the user declines `configure` and `git.trunk_branch` is among the missing keys, the CLI now states that `/prd` and `/new` will autodetect the trunk and warn until the key is set, replacing the previous (inaccurate for this key) "skills will prompt for the missing keys on first use" reassurance.
+
 ## [4.1.0] - 2026-06-02
 
 **Portability: framework-wide path-literal de-contamination (`docs/…`, `backlog/`, `src/components/…` → `${paths.*}`) + new `paths.docs_dir` config key.** Closes the open follow-up forward-referenced in v4.0.3: a dedicated, per-occurrence judgment pass over the path-literals `contamination.js` flags across `framework/`. The scanner's `autofixable` count drops **219 → 49**; the 49 survivors are legitimate and intentionally kept. The new `paths.docs_dir` config key makes this **MINOR**.

package/VERSION

@@ -1 +1 @@
-4.1.0
+4.1.1

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

@@ -16,7 +16,7 @@ description: >
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; default `develop`), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer`.
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `git.trunk_branch` (integration trunk; autodetected from `origin/HEAD` when the key is absent — see Phase 0 step 0), `git.merge_strategy`, `paths.high_risk_modules` (risk-detector path list), `paths.metrics` (default `docs/metrics`), `stack.language` / `stack.database` / `stack.deployment` (gate guards), and `features.has_e2e_review` / `features.has_design_system` / `features.has_lsp_layer`.
 **Gated by features:** `features.has_backlog` (skill REFUSES to run when `false` — this orchestrator operates on backlog cards by definition).
 **Overlay:** loads `.baldart/overlays/new.md` if present — project-specific canonical-docs registry (e.g. ssot-registry, linking-protocol guides), tooling paths (e.g. validation scripts).
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -130,7 +130,7 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
 0. **Feature gate + config resolution (BLOCKING)** — before anything else:
    - Read `features.has_backlog` from `baldart.config.yml`. If it is `false` (or the key is absent and the user confirms there is no backlog), this skill REFUSES to run: print "`/new` operates on backlog cards and requires `features.has_backlog: true` — run `npx baldart configure` to enable." and HALT. Do NOT proceed to step 1.
-   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml` (default `develop` only when the key is absent). Persist it as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from config".
+   - Resolve `$TRUNK` = `git.trunk_branch` from `baldart.config.yml`. **When the key is absent** (consumer updated to ≥4.0.0 without re-running `configure`), do NOT hard-assume `develop` — autodetect the repo's real default branch exactly as worktree-manager does, so `/new` and `nw` agree on the base: `git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD` (strip `refs/remotes/origin/`), else the first existing local branch among `develop` / `main` / `master`. A `main`-trunk repo defaulted to `develop` here would diverge from the worktree base `nw` picks and break every `git diff "$TRUNK...HEAD"` gate. Only HALT ("Trunk branch unresolved — run `npx baldart configure`") if nothing resolves. Persist the resolved value as `Trunk branch:` in the tracker `## Worktree` section. **Every later Phase 0 / Phase 6c bash snippet that references the integration trunk MUST use `$TRUNK`, never a baked-in `develop`.** Begin every later consumer with a guard: if `$TRUNK` is empty → HALT with "Trunk branch unresolved — re-read `git.trunk_branch` from the tracker".
 
 1. **Resolve `$MAIN`** — the absolute path of the main repo (not a worktree). If `/new` was invoked from inside a worktree, walk up to the parent repo via `git rev-parse --show-superproject-working-tree` or `git worktree list` until you find the non-worktree root. Persist as `Main repo:` in the tracker `## Worktree` section. **Write `$MAIN` to the tracker the moment it is computed** — every later consumer (Phase 6c, Phase 6b) MUST re-read it from the tracker and HALT with "`$MAIN` absent from tracker" if the field is missing or empty, never silently use an undefined `$MAIN` (it does not survive context compaction).
 
@@ -1280,7 +1280,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 Run this exact bash block in the worktree. It is deterministic (grep + path match), not LLM-discretionary.
 
-`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, default `develop`). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
+`$TRUNK` is the trunk branch resolved in Phase 0 (`git.trunk_branch`, autodetected when the key is absent — see Phase 0 step 0). `$HIGH_RISK_RE` is an alternation built from `paths.high_risk_modules` in `baldart.config.yml` (e.g. `path1|path2|withAuth`). **If `paths.high_risk_modules` is absent, the path-based triggers (#1) emit a one-line diagnostic and match nothing — no hardcoded project path is baked in.**
 
 ```bash
 cd <worktree-path>

package/framework/.claude/skills/prd/assets/state-template.md

@@ -6,7 +6,7 @@ stats_enabled: {{true if invoked with -stats/--stats, else false}}
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}
 - main_path: {{absolute path of the MAIN repo checkout ($MAIN) — persisted at Step 1 so finalization (validation-phase Step 7.5) never references an undefined var}}
-- trunk_branch: {{resolved git.trunk_branch (default develop)}}
+- trunk_branch: {{resolved git.trunk_branch (autodetected from origin/HEAD when the config key is absent)}}
 - branch: prd/{{slug}}
 - kind: docs
 - created_at: {{ISO-8601 UTC}}

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

@@ -149,12 +149,17 @@ la feature prima di scrivere qualsiasi documento.
 <Progress Bar>
 ```
 
-**MONITORING SIGNAL (non-blocking):** docs worktree created (registry entry with
-`kind: "docs"` present) AND state file exists on disk inside the worktree AND
-all tasks created AND context loaded. These are logged for observability; they
-do not halt execution. Precondition failures that would surface as a STOP are
-already handled by the BLOCKING gates in points 3 and 4 above — this note is
-a post-completion consistency reminder only, not an additional gate.
+**Gate (BLOCKING).** Before leaving Step 1 you MUST verify, on disk, that the
+docs worktree actually exists: `pwd` prints the absolute worktree path AND its
+registry entry (`kind: "docs"`) is present AND the state file exists inside the
+worktree AND all tasks were created AND context loaded. If the worktree was NOT
+created — e.g. `nw-docs` aborted because no trunk branch could be resolved, or
+`.worktrees/` is not in `.gitignore` — **HALT and surface the `nw-docs` error
+verbatim**. Do NOT show the "Ho creato la sessione PRD … in un worktree
+dedicato" message and do NOT proceed to Discovery: writing PRD artefacts on the
+main checkout breaks HARD RULE 17 and pollutes every parallel session. This is a
+hard gate, not an observability note — the kickoff output above is emitted only
+after this gate passes.
 
 **Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
 and ask the mockup intake question in the same turn.

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

@@ -110,14 +110,30 @@ if [ ! -f "$MAIN_ROOT/.gitignore" ] || ! grep -qE '^\.worktrees/?$' "$MAIN_ROOT/
   exit 1
 fi
 
-# 0b. Resolve the trunk branch from config (R7) — no bare 'develop' literal.
-#     TRUNK MUST be non-empty before any fetch/branch.
+# 0b. Resolve the trunk branch (R7). Prefer the config key; if the consumer
+#     updated to >=4.0.0 without re-running `configure`, `git.trunk_branch` may
+#     be absent — in that case AUTODETECT the repo's real default branch
+#     (origin/HEAD → local develop/main/master) instead of hard-failing. This is
+#     NOT "assume develop": it resolves the branch the repo actually uses, the
+#     same logic configure.js applies. Only abort when even autodetection finds
+#     nothing (bare repo / no branches). Without this fallback a config missing
+#     the v4.0.0 key silently blocked every `/prd` worktree (regression v4.0.0).
 TRUNK=$(grep -A40 '^git:' "$MAIN_ROOT/baldart.config.yml" 2>/dev/null \
   | grep 'trunk_branch:' | head -1 \
   | sed -E 's/.*trunk_branch:[[:space:]]*([A-Za-z0-9._\/-]+).*/\1/' || true)
 if [ -z "$TRUNK" ]; then
-  echo "ERROR: git.trunk_branch not set in baldart.config.yml — ASK the user (never assume 'develop')." >&2
-  exit 1
+  TRUNK=$(git -C "$MAIN_ROOT" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null \
+    | sed -E 's#^refs/remotes/origin/##' || true)
+  if [ -z "$TRUNK" ]; then
+    for cand in develop main master; do
+      if git -C "$MAIN_ROOT" show-ref --verify --quiet "refs/heads/$cand"; then TRUNK="$cand"; break; fi
+    done
+  fi
+  if [ -z "$TRUNK" ]; then
+    echo "ERROR: git.trunk_branch not set in baldart.config.yml and no trunk branch could be autodetected (origin/HEAD / develop / main / master). Run 'npx baldart configure' to set git.trunk_branch, or create the trunk branch first." >&2
+    exit 1
+  fi
+  echo "WARN: git.trunk_branch missing from baldart.config.yml — autodetected '$TRUNK'. Run 'npx baldart configure' to persist it and silence this warning." >&2
 fi
 
 # 1. Pre-flight — read-only fetch, NEVER touches main repo HEAD
@@ -344,12 +360,25 @@ Supports three modes:
 # persist both onto the registry entry created in step 6 (R6). Every later step
 # reads them from the registry with a presence guard — never from in-context state.
 MAIN="$(git rev-parse --show-toplevel)"
+# Prefer git.trunk_branch; autodetect the repo's real default branch if the
+# config key is absent (consumer updated to >=4.0.0 without re-running
+# `configure`). Same fallback as nw-docs — never hard-fail on a resolvable repo.
 TRUNK=$(grep -A40 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
   | grep 'trunk_branch:' | head -1 \
   | sed -E 's/.*trunk_branch:[[:space:]]*([A-Za-z0-9._\/-]+).*/\1/' || true)
 if [ -z "$TRUNK" ]; then
-  echo "ERROR: git.trunk_branch not set in baldart.config.yml — ASK the user (never assume 'develop')." >&2
-  exit 1
+  TRUNK=$(git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null \
+    | sed -E 's#^refs/remotes/origin/##' || true)
+  if [ -z "$TRUNK" ]; then
+    for cand in develop main master; do
+      if git -C "$MAIN" show-ref --verify --quiet "refs/heads/$cand"; then TRUNK="$cand"; break; fi
+    done
+  fi
+  if [ -z "$TRUNK" ]; then
+    echo "ERROR: git.trunk_branch not set in baldart.config.yml and no trunk branch could be autodetected (origin/HEAD / develop / main / master). Run 'npx baldart configure' to set git.trunk_branch, or create the trunk branch first." >&2
+    exit 1
+  fi
+  echo "WARN: git.trunk_branch missing from baldart.config.yml — autodetected '$TRUNK'. Run 'npx baldart configure' to persist it." >&2
 fi
 
 # Fetch latest trunk from remote — read-only, does NOT touch the main repo's HEAD.

package/package.json

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

package/src/commands/update.js

@@ -1172,6 +1172,11 @@ async function update(options = {}, unknownArgs = []) {
                 await configureCmd(autoYes ? { nonInteractive: true } : undefined);
               } else {
                 UI.info('Skipped. Skills will prompt for the missing keys on first use.');
+                if (allMissing.includes('git.trunk_branch')) {
+                  UI.warning('`git.trunk_branch` drives worktree creation in `/prd` and `/new`. '
+                    + 'Until it is set, those skills autodetect the trunk (origin/HEAD → develop/main/master) '
+                    + 'and warn on each run; run `npx baldart configure` to persist it and make it deterministic.');
+                }
               }
             }
           } catch (_) {