baldart 4.0.4 → 4.1.1

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.
@@ -709,7 +738,7 @@ internal structure (tables, key/value blocks, code).
 | **Structured registries** | `project-status.md`, `ssot-registry.md`, `field-registry.*`, `traceability-matrix.md`, `REGISTRY.md` | Strip markers, then **structural validation** — if valid, accept; if invalid, abort | The auto-strip "keep both sides" usually produces an additive result (new bullet rows appended to a table or section). The validation step catches the rare case where the two sides modified the same row. See `validate_structured_md` below. |
 | **JSONL logs under `${paths.metrics}/`** | `${paths.metrics}/*.jsonl`, `${paths.metrics}/**/*.jsonl` | Auto-resolve: strip markers, keep both sides | JSONL is line-oriented and additive — duplicating both branches' lines yields a valid file. (`paths.metrics` default `docs/metrics`.) |
 | **Other `.jsonl`** | `*.jsonl` outside `${paths.metrics}/` | STOP — abort and report | Fixtures, seeds, training data: auto-strip can corrupt them. The user must inspect. |
-| **Docs/config** | `docs/**/*.md`, `backlog/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` (excluding rows above) | Auto-resolve: strip markers, keep both sides | The canonical additive case. |
+| **Docs/config** | `${paths.docs_dir}/**/*.md`, `${paths.backlog_dir}/*.yml`, `*.md` outside `src/`, `*.json`/`*.yml` outside `src/` (excluding rows above) | Auto-resolve: strip markers, keep both sides | The canonical additive case. |
 | **Code** | `src/**/*.ts`, `*.tsx`, `*.js`, `*.jsx` | STOP — abort rebase, report to user | |
 | **Tests** | `*.test.*`, `*.spec.*` | Manual only — report to user | |
 
@@ -784,7 +813,7 @@ for FILE in $CONFLICTED; do
 
   # 4. Generic docs/config — additive merge
   case "$FILE" in
-    docs/*|backlog/*|*.md|*.json|*.yml)
+    ${paths.docs_dir}/*|${paths.backlog_dir}/*|*.md|*.json|*.yml)
       sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
       git add "$FILE" ;;
   esac

package/framework/agents/project-context.md

@@ -174,6 +174,7 @@ When `base_agent_version` in the overlay is older than the installed framework v
 | Backlog | `backlog/*.yml` count > 0 | `paths.backlog_dir: backlog`, `features.has_backlog: true` |
 | ADR | `docs/decisions/ADR-*.md` count > 0 | `paths.adrs_dir: docs/decisions`, `features.has_adrs: true` |
 | PRD | `docs/prd/` exists | `paths.prd_dir: docs/prd`, `features.has_prd_workflow: true` |
+| Docs root | `docs/` exists | `paths.docs_dir: docs` |
 | References dir | `docs/references/` exists | `paths.references_dir: docs/references` |
 | LLM wiki | `docs/wiki/` exists | `paths.wiki_dir: docs/wiki`, `features.has_wiki_overlay: true` |
 | E2E tests | first match of `tests/e2e`, `e2e`, `tests/playwright`, `tests/cypress` | `paths.e2e_tests_dir: <found>` |

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -105,6 +105,7 @@ Empty string `""` means the concept doesn't exist in your project. Skills gated
 | `backlog_dir` | `backlog` | new, prd, context-primer |
 | `adrs_dir` | `docs/decisions` | prd, prd-add |
 | `prd_dir` | `docs/prd` | prd, prd-add, ui-design |
+| `docs_dir` | `docs` | code-reviewer, senior-researcher, worktree-manager (rg-search fallback root) |
 | `references_dir` | `docs/references` | new, prd, context-primer, doc-writing-for-rag, simplify |
 | `wiki_dir` | `docs/wiki` | capture, context-primer |
 | `e2e_tests_dir` | `tests/e2e` | playwright-skill, e2e-review (v3.18.0) |

package/framework/routines/ds-drift.routine.yml

@@ -11,21 +11,21 @@ schedule:
 agent: doc-reviewer
 
 prompt: |
-  Run the weekly design-system drift check (only if `docs/design-system/`
+  Run the weekly design-system drift check (only if `${paths.design_system}/`
   exists in the project — exit cleanly if absent):
 
-  1. **INDEX coverage**: compare `docs/design-system/INDEX.md` component
+  1. **INDEX coverage**: compare `${paths.design_system}/INDEX.md` component
      index against the actual shared-component inventory. Flag
      `DS_INDEX_DRIFT` for any mismatch.
-  2. **Per-component accuracy**: for each `docs/design-system/components/<Name>.md`,
+  2. **Per-component accuracy**: for each `${paths.design_system}/components/<Name>.md`,
      verify it lines up with the source file (variants, props, exported
      constants). Flag `DS_COMPONENT_STALE` for docs not re-verified in >7
      days where the source has changed in git.
-  3. **Animations reconciliation**: `docs/design-system/patterns/animations.md`
+  3. **Animations reconciliation**: `${paths.design_system}/patterns/animations.md`
      must match keyframes in the project's global styles. Flag
      `DS_ANIMATIONS_DRIFT`.
   4. **Tokens reconciliation**: when tokens source files changed, verify
-     `docs/design-system/tokens-reference.md` is in sync and the relevant
+     `${paths.design_system}/tokens-reference.md` is in sync and the relevant
      CSS custom properties still exist. Flag `DS_TOKENS_DRIFT`.
   5. Emit a consolidated report under
      `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
@@ -41,7 +41,7 @@ output:
     branch: main
 
 required_artifacts:
-  - docs/design-system/
+  - ${paths.design_system}/
   - .claude/agents/doc-reviewer.md
 
 optional: true   # routine is silently skipped when artifacts missing

package/framework/routines/wiki-review.routine.yml

@@ -1,5 +1,5 @@
 name: wiki-review
-description: Nightly review of the derived LLM wiki overlay (docs/wiki/) — synthesis candidates, anchor validation, drift detection.
+description: Nightly review of the derived LLM wiki overlay (${paths.wiki_dir}/) — synthesis candidates, anchor validation, drift detection.
 since_version: 2.1.0
 
 schedule:
@@ -16,8 +16,8 @@ prompt: |
   1. Scan ADRs and PRDs from the last 14 days. For each architectural pivot
      (provider swap, schema change, auth change, API contract, multi-card
      epic) propose a synthesis page candidate and append it to
-     `docs/wiki/log.md` with `entry_type: synthesis_candidate`.
-  2. Read `docs/wiki/log.md` for RAG queries with verdict=weak|empty
+     `${paths.wiki_dir}/log.md` with `entry_type: synthesis_candidate`.
+  2. Read `${paths.wiki_dir}/log.md` for RAG queries with verdict=weak|empty
      repeated ≥3 times. These are documentation gaps — propose a synthesis.
   3. Validate anchor slugs across all wiki pages (internal and cross-file).
      Flag `WIKI_ANCHOR_BROKEN` and fix in-place when possible.
@@ -36,7 +36,7 @@ output:
 
 required_artifacts:
   # Routine is silently skipped if these are missing.
-  - docs/wiki/
+  - ${paths.wiki_dir}/
   - .claude/agents/wiki-curator.md
 
 backend_hints:

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

@@ -39,6 +39,7 @@ paths:
   backlog_dir: ""             # e.g. backlog
   adrs_dir: ""                # e.g. docs/decisions
   prd_dir: ""                 # e.g. docs/prd
+  docs_dir: ""                # e.g. docs   (umbrella docs root; rg-search fallback used by code-reviewer / senior-researcher / worktree-manager)
   references_dir: ""          # e.g. docs/references
   wiki_dir: ""                # e.g. docs/wiki   (LLM-wiki overlay)
 

package/framework/templates/overlays/commands/codexreview.example.md

@@ -4,6 +4,8 @@ base_command_version: 3.8.0
 mode: extend
 ---
 
+<!-- contamination-scan: skip — starter overlay EXAMPLE the user copies and rewrites; ships intentional sample literals (project build names, CTP-NNNN ids, backlog/, src/lib/...) by design. Overlays hold verbatim user opinions and are NOT runtime-resolved against baldart.config.yml. -->
+
 > Copy to `.baldart/overlays/commands/codexreview.md` and adapt freely.
 > Same merge model as agent overlays: `[OVERRIDE]` / `[APPEND]` / `[PREPEND]`
 > with H2 heading matching, plus untagged H2 sections appended at the end.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.0.4",
+  "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/configure.js

@@ -370,6 +370,7 @@ function detect(cwd = process.cwd()) {
       backlog_dir: exists('backlog') ? 'backlog' : '',
       adrs_dir: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0 ? 'docs/decisions' : '',
       prd_dir: exists('docs/prd') ? 'docs/prd' : '',
+      docs_dir: exists('docs') ? 'docs' : '',
       references_dir: exists('docs/references') ? 'docs/references' : '',
       wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
       e2e_tests_dir: e2eTestsDir,
@@ -640,6 +641,7 @@ async function interactivePrompts(merged, detected) {
     ['backlog_dir', 'Backlog directory', () => merged.features.has_backlog],
     ['adrs_dir', 'ADR directory', () => merged.features.has_adrs],
     ['prd_dir', 'PRD directory', () => merged.features.has_prd_workflow],
+    ['docs_dir', 'Docs root directory (rg-search umbrella)', () => true],
     ['references_dir', 'References docs root', () => true],
     ['wiki_dir', 'Wiki overlay directory', () => merged.features.has_wiki_overlay],
     ['e2e_tests_dir', 'E2E tests directory', () => true],

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 (_) {