baldart 4.45.0 → 4.46.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.46.0] - 2026-06-15
+
+**Worktree env-file copy is unified onto one stack-agnostic config key, `stack.env_files` — closing the v4.42.0-deferred divergence (`/nw` copied `.env.local`+`.env`; new2's pre-flight copied `env/.env.local/.env.example/supabase/.temp`) WITHOUT the superset the adversarial pass had refuted.** A worktree is a fresh checkout, so the gitignored env artifacts a build needs must be copied from main — but the SET was hard-coded and divergent across paths. This release makes the set a single SSOT list (`stack.env_files`, default `['.env.local', '.env']`) read identically by `worktree-manager` (`/nw`), `/new`, and `new2`. A 3-skeptic **adversarial review before implementation** shaped the design: it (1) confirmed `framework/agents/runbook.md:36` (`cp .env.example .env`) is a documentation-template onboarding idiom — a DIFFERENT context — and **excluded** it; (2) refuted folding `supabase/.temp` into the copy set (it carries the remote project-ref → every copying worktree auto-links to the shared remote, the exact footgun `stack.schema_deploy_from_trunk_only` exists to prevent, and worse unattended in `/new` than in manual `/nw`; it is not even a build input); and (3) found the bash bug class fixed below. Crucially, the layer is **stack-agnostic**: the generic skill/installer/template never name Supabase or any stack — copying a tool's local-state directory is a per-project opt-in the user adds to their own `stack.env_files` / overlay, never a framework default. **MINOR** (additive: a new `baldart.config.yml` key, propagated end-to-end per the schema-change rule; no removed surface).
+
+### Added
+
+- **`stack.env_files` config key** (`framework/templates/baldart.config.template.yml`) — list of gitignored env artifacts (files OR dirs) copied into each worktree, default `['.env.local', '.env']`. Files are copied with `cp` (dereferences symlinks — never `cp -P`, which would dangle a relative env symlink inside `.worktrees/`), directories with `cp -r` (mirrored: stale files removed on a `/nw` resume). A missing FILE is WARNed at copy time (never `exit 1` — that would strand `/new`'s programmatic path; the build gate is the real enforcement); nothing-copied escalates to a loud WARN. Replaces the old `cp … 2>/dev/null || true` that silently swallowed a missing critical env → cryptic later build failure.
+
+### Changed
+
+- **`framework/.claude/skills/worktree-manager/SKILL.md` — `/nw` step 4 copy loop reads `stack.env_files`** (file/dir-aware, WARN-not-fatal). The dev-server PORT is now written to the first FILE actually copied (not `ENV_FILES[0]`, which could be a directory — `echo >> dir` errors), falling back to `.env.local`. The env-sync staleness check (`/mw` step 2) compares the NEWEST mtime among all `stack.env_files` (portable `stat -f %m || stat -c %Y`, recursive for dirs) instead of only `.env.local`; the `/lw` status line, the port-reuse rule, the docs-mode "forbidden" list, and the Project-Context header are reconciled to the list. The skill stays **stack-agnostic** — it iterates the list and never names a stack.
+- **`framework/.claude/workflows/new2.js` + `framework/.claude/skills/new/references/setup.md`** — the pre-flight worktree briefing stops hard-coding `env/.env.local/.env.example/supabase/.temp` and copies `stack.env_files` instead (new2 interpolates the list resolved from `args.config`). `.env.example` is dropped (tracked → already in the checkout).
+- **`src/commands/configure.js`** — autodetects `stack.env_files` from the universal gitignored env conventions (`.env.local`/`.env`) only (stack-agnostic — no per-database special-casing), a comma-separated interactive prompt, and a summary-box line.
+- **`src/commands/update.js`** — the `missingStack` detector now also catches top-level ARRAY stack keys (`stack.env_files` is `typeof 'object'`, so it needs `Array.isArray`); sub-object keys (`charting`/`animation`/`testing`) stay excluded (`Array.isArray({}) === false`). Without this the new key would silently never be asked on update.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — documents `stack.env_files` (§4.4) as a stack-agnostic list.
+
 ## [4.45.0] - 2026-06-15
 
 **The main-repo-root (`$MAIN`) resolution across `worktree-manager` + `/prd` + `/new` is unified onto one correct, `separate-git-dir`-safe canonical — fixing two latent bugs while *refuting* the obvious "unify on `--git-common-dir`" fix the deferred plan proposed.** v4.42.0 deferred the `$MAIN` cleanup after an adversarial pass flagged it as a likely trap; this release does it properly. The root resolution lived in ~5 forms across three genuine execution contexts (main-checkout cwd, worktree cwd, the `allocate-id.sh` startup), and the deferred plan wanted to collapse them onto `git rev-parse --git-common-dir` + `/..` (the recipe already in `allocate-id.sh` `resolve_main()`). A 3-skeptic adversarial review **before implementation** demolished that plan with git experiments: (1) `--git-common-dir` + parent returns the *parent of the git dir*, which is the WRONG directory under `git init --separate-git-dir` (the git dir lives outside the working tree) — so the "canonical" recipe was itself fragile, and `resolve_main()` only worked because BALDART repos use in-tree `.git`; (2) the alleged `prd/SKILL.md` Step-1 bug ("`--show-toplevel` from inside a worktree") does **not** exist — Step 1 runs only at fresh kickoff on the main checkout, and resume reads the persisted `main_path`, so `--show-toplevel` is correct there *and* is the only form that survives `separate-git-dir`; (3) `git worktree list` head is also not `separate-git-dir`-safe (returns the git dir). The corrected design keeps the task's **context classification** but fixes the **primitive**: every site resolves the root through `--show-toplevel` (the true working-tree root in all cases), using `git -C .. rev-parse --show-toplevel` from a worktree (its parent `.worktrees/` lives inside the main repo). `resolve_main()` is rewritten as the canonical reference (detects a linked worktree via `git-dir != git-common-dir`, walks one level up) — **byte-identical output to the old form for in-tree repos** (verified), correct for `separate-git-dir`, and fails cleanly (`return 1`) instead of emitting a garbage path. Two real fragilities fixed along the way: the `/mw` `$MAIN` fallback (`--git-common-dir` + `/..` under `git -C`, relative-base hazard + `separate-git-dir` break) and the `3b` card-sync (`--show-superproject-working-tree || pwd`, which returned the SUPERPROJECT for a real submodule and only worked otherwise by a cwd accident). All recipes dogfooded across normal + `separate-git-dir` repos in every cwd context. **MINOR** (hardening + bug fixes across skills/agents; no removed surface, **no new `baldart.config.yml` key** ⇒ schema-change propagation rule N/A).

package/VERSION

@@ -1 +1 @@
-4.45.0
+4.46.0

package/framework/.claude/skills/new/references/setup.md

@@ -287,7 +287,9 @@
         { cards: [<all card IDs>], groupParent: <PARENT-ID|null>, slug: "<slug>" }
       Let it: group cards, derive the branch from git_strategy.branch (fallback
       feat/<PARENT-ID>-<slug>), create the worktree in .worktrees/, install deps,
-      copy env files, assign a free port, update .worktrees/registry.json (all card
+      copy the gitignored env artifacts in stack.env_files (files via cp, dirs via
+      cp -r; missing file → WARN, never abort), assign a free port, update
+      .worktrees/registry.json (all card
       IDs in the `cards` field), and run the baseline (tsc + lint + build)
       UNDER A HARD TIMEOUT — wrap the build step in `timeout 600 <build-cmd>`
       (10 min) so a hung or interactive build cannot stall the pre-flight barrier.

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

@@ -20,6 +20,7 @@ description: >
 - `git.merge_strategy` — `pr` (default, GitHub PR via `gh`) or `local-push` (direct fast-forward to `origin/<git.trunk_branch>`). Drives `/mw` step 4c.
 - `paths.backlog_dir` — used for syncing untracked backlog cards (`/nw` step 3b).
 - `paths.metrics` — JSONL telemetry dir (default `docs/metrics`) used by the rebase conflict-resolution table.
+- `stack.env_files` — list of gitignored env artifacts (files OR dirs) copied into each worktree (`/nw` step 4). Default `['.env.local', '.env']`. The SAME list drives /nw, /new, and new2 — no per-path divergence. NEVER list a tracked file (already in the checkout). The skill is stack-agnostic — it just iterates the list; any project-specific entry (e.g. a tool's local-state dir) is the project's own opt-in in its config/overlay.
 - `features.has_toolchain` + `toolchain.commands.{typecheck,lint,build,test}` — when the flag is `true`, the mechanical gates below run the consumer's configured commands verbatim instead of the hardcoded `npx tsc`/`npx eslint`/`npm run build` defaults (see "## Toolchain-aware gates"). Absent/`false` → defaults, identical to pre-toolchain behavior.
 - Protocol reference: `framework/agents/project-context.md`. Skills must ASK when a needed key is missing — never assume.
 
@@ -108,7 +109,7 @@ backlog cards, design references — and never touch source code.
 What docs mode SKIPS vs the standard flow:
 - No `npm install` (no `node_modules/` inside the worktree)
 - No port allocation (no dev server)
-- No `.env`/`.env.local` copy
+- No env-artifact (`stack.env_files`) copy
 - No `npm run build` baseline verification
 - No lint / tsc baseline checks
 - No `--dev` server bootstrap
@@ -240,7 +241,7 @@ git -C "$MAIN_ROOT" worktree add "$WORKTREE_REL" -b "$BRANCH" "origin/$TRUNK"
 }
 ```
 
-**Forbidden in docs mode**: `npm install`, port scan, `.env*` copy, `npm run build`,
+**Forbidden in docs mode**: `npm install`, port scan, `.env*`/`stack.env_files` copy, `npm run build`,
 `npx tsc`, `npx eslint`, dev server start, `git checkout`/`switch`/`branch` on main.
 
 ### mw-docs programmatic
@@ -633,8 +634,19 @@ npm install
 # 2. Own .next cache — already isolated since each worktree has its own
 #    directory tree. The default .next inside the worktree is sufficient.
 
-# 3. Copy environment files from main repo root
-#    Build requires Firebase env vars — this copy is critical.
+# 3. Copy environment artifacts from main repo root.
+#    The build typically requires gitignored env secrets, so this copy is
+#    critical — but the SET is project-specific and lives in `stack.env_files`
+#    (baldart.config.yml). Resolve that list and emit it LITERALLY below as a bash
+#    array (default ('.env.local' '.env') when the key is absent). List ONLY
+#    gitignored artifacts: a tracked file (e.g. an example env committed to git)
+#    is already in the worktree checkout — copying it is redundant. Entries may be
+#    FILES (cp) or DIRECTORIES (cp -r). The SAME list drives /nw, /new, and new2 —
+#    no per-path divergence. (A directory entry that carries remote-link/credential
+#    state makes the worktree act on the same remote as main; that is a per-project
+#    opt-in the user adds to stack.env_files / their overlay — the skill itself is
+#    stack-agnostic and just iterates the list.)
+#
 #    cwd is the worktree; its parent (`.worktrees/`) lives inside the main repo,
 #    so `git -C ..` resolves the MAIN repo's toplevel — correct under a
 #    `--separate-git-dir` repo too (unlike `--git-common-dir`+parent). The old
@@ -642,8 +654,42 @@ npm install
 #    guess; fail loud instead. See § "Resolving the main repo root".
 MAIN_ROOT="$(git -C .. rev-parse --show-toplevel 2>/dev/null)"
 [ -n "$MAIN_ROOT" ] || { echo "ERROR: cannot resolve main repo root from worktree $(pwd)" >&2; exit 1; }
-cp "$MAIN_ROOT/.env.local" .env.local 2>/dev/null || true
-cp "$MAIN_ROOT/.env" .env 2>/dev/null || true
+
+# <resolve stack.env_files and emit each entry quoted; default if the key is absent>
+ENV_FILES=( ".env.local" ".env" )
+copied_any=0
+primary_env=""                          # first FILE actually copied — PORT target (step 4)
+for ef in "${ENV_FILES[@]}"; do
+  src="$MAIN_ROOT/$ef"
+  dest_dir="$(dirname "$ef")"
+  if [ -d "$src" ]; then
+    # Directory artifact. cp -r MERGES into an existing
+    # dest, so mirror it: remove first to avoid stale files lingering on a /nw
+    # resume. Judge success by dest existence, NOT cp's exit code (BSD `cp -r`
+    # returns non-zero on a broken inner symlink while still copying the rest).
+    mkdir -p "$dest_dir"
+    rm -rf "$ef"
+    cp -R "$src" "$dest_dir"/ 2>/dev/null || true
+    [ -e "$ef" ] && copied_any=1 || echo "WARN: env dir '$ef' (stack.env_files) present in main but copy failed — worktree may be incomplete." >&2
+  elif [ -f "$src" ]; then
+    # File artifact. PLAIN cp (NEVER cp -P): it dereferences a symlinked source,
+    # so an `.env.local -> ../shared/.env` symlink yields real content here — a
+    # preserved relative symlink would dangle inside `.worktrees/feat-X/`.
+    mkdir -p "$dest_dir"
+    if cp "$src" "$ef"; then copied_any=1; [ -z "$primary_env" ] && primary_env="$ef"; fi
+  else
+    # Absent in main. A missing FILE is the critical case (build likely needs it):
+    # WARN loudly so a later cryptic build failure is diagnosable — but NEVER exit 1
+    # (this runs on /new's programmatic path; aborting would strand the batch — the
+    # build gate in step 5 is the real enforcement). A missing DIR is best-effort
+    # (the worktree just isn't linked, which is safe) — we cannot stat a nonexistent
+    # path to know it was a dir, so a single neutral WARN per entry covers both.
+    echo "WARN: env artifact '$ef' (stack.env_files) not found in $MAIN_ROOT — the worktree build may fail if it is required." >&2
+  fi
+done
+if [ "$copied_any" = 0 ] && [ "${#ENV_FILES[@]}" -gt 0 ]; then
+  echo "WARN: NO env artifacts copied into the worktree (none of: ${ENV_FILES[*]} exist in $MAIN_ROOT). If the build needs env vars it WILL fail — add the file(s) to the main repo or fix stack.env_files." >&2
+fi
 
 # 4. Pick a free dev server port (avoid 3000 used by main)
 PORT=3001
@@ -651,11 +697,15 @@ while lsof -i :$PORT -sTCP:LISTEN >/dev/null 2>&1; do
   PORT=$((PORT + 1))
   if [ $PORT -gt 3099 ]; then echo "ERROR: No free port in 3001-3099" >&2; exit 1; fi
 done
-# Write PORT to .env.local (append or replace existing PORT line)
-if grep -q "^PORT=" .env.local 2>/dev/null; then
-  sed -i '' "s/^PORT=.*/PORT=$PORT/" .env.local
+# Write PORT to the project's PRIMARY env file — the first FILE that was actually
+# copied (NOT ENV_FILES[0], which could be a directory entry, where
+# `echo >> dir` / `grep dir` error out). Fall back to .env.local when nothing was
+# copied so a port is still persisted somewhere the dev server can read.
+PORT_ENV_FILE="${primary_env:-.env.local}"
+if grep -q "^PORT=" "$PORT_ENV_FILE" 2>/dev/null; then
+  sed -i '' "s/^PORT=.*/PORT=$PORT/" "$PORT_ENV_FILE"
 else
-  echo "PORT=$PORT" >> .env.local
+  echo "PORT=$PORT" >> "$PORT_ENV_FILE"
 fi
 
 # 5. ASSERT git hooks are ACTIVE — not just readable.
@@ -776,12 +826,32 @@ fi
 
 ### 2. Env sync check
 
-Compare main repo `.env.local` modification time with registry `envSyncedAt`.
-If main `.env.local` is newer, WARN:
+Compare the NEWEST modification time among the `stack.env_files` artifacts in the
+main repo against the registry `envSyncedAt`. If any is newer, WARN. Use a
+portable mtime read (`stat -f %m` is BSD/macOS, `stat -c %Y` is GNU/Linux — the
+snippet runs on both) and scan directory entries recursively (a directory's own
+mtime does NOT bump when a nested file is edited in place):
 
-```
-Warning: Main repo .env.local has changed since this worktree was created.
-Consider updating the worktree's .env.local before merging.
+```bash
+# Resolve stack.env_files the same way step 4 does; emit it literally here.
+ENV_FILES=( ".env.local" ".env" )
+mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null; }
+newest=0
+for ef in "${ENV_FILES[@]}"; do
+  src="$MAIN/$ef"
+  if [ -d "$src" ]; then
+    # newest mtime of any file inside the dir (recursive)
+    while IFS= read -r f; do m=$(mtime "$f"); [ "${m:-0}" -gt "$newest" ] && newest=$m; done \
+      < <(find "$src" -type f 2>/dev/null)
+  elif [ -f "$src" ]; then
+    m=$(mtime "$src"); [ "${m:-0}" -gt "$newest" ] && newest=$m
+  fi
+done
+SYNCED=$(mtime "$WORKTREE_PATH/.env-synced-marker" 2>/dev/null)   # or parse registry envSyncedAt → epoch
+if [ "${newest:-0}" -gt "${SYNCED:-0}" ]; then
+  echo "Warning: a main-repo env artifact (stack.env_files) changed since this worktree was created."
+  echo "Consider re-copying the env files into the worktree before merging."
+fi
 ```
 
 ### 3. Pre-merge safety commit + checks inside the worktree
@@ -1314,7 +1384,7 @@ Active worktrees:
      Age:    2 days
      Status: 3 uncommitted changes
      Build:  verified ✓
-     Env:    in sync | STALE (main .env.local changed)
+     Env:    in sync | STALE (a main env artifact changed)
 
   2. BUG-0500 fix-auth
      Branch: feat/BUG-0500-fix-auth
@@ -1418,5 +1488,5 @@ Cleanup complete:
 - If merge conflicts during /mw, STOP and ask the user. Do not auto-resolve.
 - Always verify `.worktrees/` is in `.gitignore` before creating it (the nw-docs pre-flight in step 0 enforces this; add it before running if absent).
 - Commit lock protocol: Each worktree has its own `COMMIT_LOCK` in its git dir — no cross-worktree interference.
-- Port persistence: On dev server restart, reuse the port from registry (grep .env.local for PORT=) instead of picking a new one.
+- Port persistence: On dev server restart, reuse the port from registry (or grep the worktree's primary env file — the first FILE entry of `stack.env_files` that was copied, default `.env.local` — for `PORT=`) instead of picking a new one.
 - **NEVER use `git stash` in worktrees.** Stashes are globally shared across all worktrees (`refs/stash` via `git.commondir`). A stash created in one worktree or in the main repo can be popped in another, causing conflicts, data loss, and cascading merge failures (see FEAT-0522 incident). Use explicit file staging only — the file ownership map ensures no overlap between cards. The stash pattern in AGENTS.md/CLAUDE.md applies ONLY to the main repo working tree.

package/framework/.claude/workflows/new2.js

@@ -62,6 +62,10 @@ const paths = cfg.paths || {}
 const gitCfg = cfg.git || {}
 const stack = cfg.stack || {}
 const highRisk = paths.high_risk_modules || []
+// Gitignored env artifacts copied into the worktree (v4.46.0). SAME contract as
+// /nw + /new (worktree-manager step 4): the SSOT is stack.env_files; never list a
+// tracked file (.env.example is already in the checkout). Default minimal set.
+const ENV_FILES = (Array.isArray(stack.env_files) && stack.env_files.length) ? stack.env_files : ['.env.local', '.env']
 const mergeStrategy = gitCfg.merge_strategy || 'pr'
 // Stack-agnostic schema-deploy safety invariant (v4.33.0). When true, a remote
 // schema/RLS/index/migration deploy is auto-executed ONLY from the trunk branch;
@@ -260,7 +264,7 @@ try {
       `ROLE BOUNDARY (specialization integrity): you are the OPS/GIT agent. You NEVER edit source or doc files — any needed content change belongs to the coder specialist; report it instead.\n\n` +
       `DETERMINISTIC GATE POLICIES (NO user prompts):\n` +
       `• G1 dirty-tree (main repo ${MAIN}): partition framework-managed noise exactly as setup.md step 3 ($METRICS=${METRICS}, .baldart/generated|state.json|skill-conflicts.json — NOT overlays/). Genuine user work → auto-stash 'baldart-new2-${firstCard}' (main checkout) and record the label. Never commit/abort/prompt.\n` +
-      `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK}; install deps; assign a port; run the baseline (tsc+lint+build). Copy ONLY the artifacts needed (env/.env.local/.env.example/supabase/.temp) — do NOT bulk-copy untracked files from the main repo (avoids stray backlog cards in the worktree). Use the git-authoritative idempotency pre-check. E2: baseline FAILS → do NOT fix it yourself (role boundary — the coder specialist repairs it); return baseline:'fail' + a baselineLog precise enough for a coder to act (failing command, error excerpt, suspect files). Wrap the build in \`timeout 600 <build-cmd>\` (10 min); if killed, return baseline:'timeout' + the partial log. On baseline PASS, VERIFY the worktree on disk and return EVIDENCE (not just a flag): set worktreeVerified:true ONLY after running \`git -C ${MAIN} worktree list --porcelain\` (the worktree path MUST appear in the output) AND \`test -d <wt>/node_modules\` AND confirming the branch; put the LITERAL stdout into worktreeEvidence{ worktreeListPorcelain, artifactsLs:\`ls -la <wt>/node_modules <wt>/.next 2>/dev/null | head\`, baselineLogTail }. The workflow string-matches this evidence — NEVER report worktreeVerified:true without actually running the commands.\n` +
+      `• Worktree (setup.md step 4): create ONE code worktree off ${TRUNK}; install deps; assign a port; run the baseline (tsc+lint+build). Copy the gitignored env artifacts in stack.env_files (resolved: ${JSON.stringify(ENV_FILES)}) — FILES via \`cp\` (plain cp, dereferences symlinks; never cp -P), DIRS via \`cp -r\`; a missing FILE → WARN (never abort). Do NOT add .env.example (tracked → already in the checkout) and do NOT bulk-copy untracked files from the main repo (avoids stray backlog cards in the worktree). Use the git-authoritative idempotency pre-check. E2: baseline FAILS → do NOT fix it yourself (role boundary — the coder specialist repairs it); return baseline:'fail' + a baselineLog precise enough for a coder to act (failing command, error excerpt, suspect files). Wrap the build in \`timeout 600 <build-cmd>\` (10 min); if killed, return baseline:'timeout' + the partial log. On baseline PASS, VERIFY the worktree on disk and return EVIDENCE (not just a flag): set worktreeVerified:true ONLY after running \`git -C ${MAIN} worktree list --porcelain\` (the worktree path MUST appear in the output) AND \`test -d <wt>/node_modules\` AND confirming the branch; put the LITERAL stdout into worktreeEvidence{ worktreeListPorcelain, artifactsLs:\`ls -la <wt>/node_modules <wt>/.next 2>/dev/null | head\`, baselineLogTail }. The workflow string-matches this evidence — NEVER report worktreeVerified:true without actually running the commands.\n` +
       codexResolveBullet +
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c): card missing requirements/acceptance_criteria/files_likely_touched → EXCLUDE (excluded[] + reason). Never HALT for one bad card.\n` +

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -162,6 +162,12 @@ stack:
 
   # Schema-deploy safety invariant (since v4.33.0). Default false (no-op).
   schema_deploy_from_trunk_only: false   # true → /new + new2 auto-deploy schema only from git.trunk_branch
+
+  # Gitignored env artifacts copied into each git worktree (v4.46.0).
+  env_files:                             # default ['.env.local', '.env']
+    - .env.local
+    - .env
+    # - some/state-dir                   # a DIR entry is copied with cp -r (project-specific opt-in)
 ```
 
 Skills propose only `canonical` libraries and refuse `forbidden` ones. Empty
@@ -196,6 +202,20 @@ the skill/agent set:
   multiple cards in parallel worktrees against one shared remote datastore. The actual
   command + env loader stay in the project overlay — core only enforces the branch gate.
   `baldart configure` defaults it to `true` when it detects parallel worktree usage.
+- `stack.env_files` (list, v4.46.0+, default `['.env.local', '.env']`) is the
+  SSOT for **gitignored env artifacts copied into each git worktree** by
+  `worktree-manager` (`/nw`), reused identically by `/new` and `new2` — no
+  per-path divergence. A worktree is a fresh checkout, so any gitignored env the
+  build needs must be copied from main. **List only gitignored artifacts** — a
+  tracked example env is already present in every checkout. Entries may be files
+  (copied with `cp`, which dereferences symlinks) or directories (copied with
+  `cp -r`). The mechanism is **stack-agnostic**: add whatever your project needs.
+  A directory that carries remote-link/credential state makes the worktree act on
+  the same remote as main — add it intentionally (and consider pairing with
+  `schema_deploy_from_trunk_only: true`). Such project-specific opinions live in
+  the project's own config value / overlay, not in the generic framework. A
+  missing FILE is WARNed at copy time (never fatal); a build that truly needs it
+  fails clearly.
 - `security-reviewer` evaluates access rules per `stack.database`
   (Firestore rules, Supabase RLS, Mongo validators, DynamoDB IAM,
   Postgres RLS+GRANT).

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

@@ -122,6 +122,24 @@ stack:
   # "render" | "fly" | "self-hosted" | "none" | "".
   deployment: ""
 
+  # Gitignored environment artifacts copied into each git worktree (since
+  # v4.46.0). A worktree is a fresh checkout, so any GITIGNORED env file/dir the
+  # build/run needs (it is NOT in the checkout) must be copied from the main repo.
+  # worktree-manager (`/nw`) reads this list; `/new` + new2 reuse the SAME list
+  # (no per-path divergence). Rules:
+  #   - List ONLY gitignored artifacts. A tracked file (e.g. an example env
+  #     committed to git) is already in every checkout — listing it is redundant.
+  #   - Entries may be FILES (copied with `cp`) or DIRECTORIES (copied with
+  #     `cp -r`). Add any project-specific entry your stack needs (e.g. a CLI's
+  #     gitignored local-state dir). NOTE: a directory carrying remote-link or
+  #     credential state makes the worktree act on the same remote as main — add
+  #     such a dir intentionally (and consider schema_deploy_from_trunk_only).
+  #   - A missing FILE here is WARNed at copy time (never fatal); a build that
+  #     truly needs it fails clearly. Default: the minimal secret set.
+  env_files:
+    - .env.local
+    - .env
+
   # Schema-deploy-from-trunk-only safety invariant (since v4.33.0). Stack-agnostic
   # guard against migration-history desync / "code-ahead-of-schema" production
   # outages on projects that develop multiple cards in PARALLEL git worktrees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.45.0",
+  "version": "4.46.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

@@ -384,6 +384,17 @@ function detect(cwd = process.cwd()) {
   else if (exists('app.yaml') || exists('cloudbuild.yaml')) detectedDeployment = 'gcp';
   // Note: bare Dockerfile → leave empty; user picks "self-hosted" or actual target.
 
+  // ---- Worktree env artifacts (stack.env_files) --------------------------
+  // GITIGNORED env files that must be copied into each worktree (they are NOT in
+  // the git checkout). Probe only the UNIVERSAL gitignored env conventions
+  // (.env.local / .env) — never a tracked file like .env.example, and never a
+  // stack-specific artifact (those are a per-PROJECT opinion: a project that
+  // needs e.g. a tool's local-state dir adds it to stack.env_files itself / via
+  // its overlay; the generic installer stays stack-agnostic). Fall back to the
+  // minimal set so the list is never empty.
+  const detectedEnvFiles = ['.env.local', '.env'].filter((f) => exists(f));
+  if (detectedEnvFiles.length === 0) detectedEnvFiles.push('.env.local', '.env');
+
   const detected = {
     paths: {
       design_system: designSystemPath,
@@ -433,6 +444,8 @@ function detect(cwd = process.cwd()) {
       // Stack-agnostic schema-deploy safety invariant (v4.33.0). Defaulted ON when
       // parallel worktrees are detected (the desync-prone topology), else false.
       schema_deploy_from_trunk_only: usesWorktrees,
+      // Gitignored env artifacts copied into each worktree (v4.46.0).
+      env_files: detectedEnvFiles,
       // New: surface the detected monorepo + DS signals so skills can read them.
       monorepo: isMonorepo ? {
         detected: true,
@@ -1057,6 +1070,20 @@ async function interactivePrompts(merged, detected) {
     'confirm'
   );
 
+  // Worktree env artifacts (stack.env_files, v4.46.0). Gitignored files/dirs
+  // copied into each worktree (stack-agnostic — the user lists whatever their
+  // project needs; a directory entry is copied recursively).
+  const envFilesDefault = (Array.isArray(merged.stack.env_files) && merged.stack.env_files.length
+    ? merged.stack.env_files
+    : detected.stack.env_files) || ['.env.local', '.env'];
+  const envFilesAns = await promptForKey(
+    'Gitignored env files/dirs copied into each worktree — comma-separated (gitignored only; NEVER a tracked file like .env.example; a directory entry is copied recursively)',
+    envFilesDefault.join(',')
+  );
+  merged.stack.env_files = envFilesAns
+    ? envFilesAns.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
   return merged;
 }
 
@@ -1141,6 +1168,7 @@ async function configure(opts = {}) {
     `Auth provider:   ${detected.stack.auth_provider || '—'}`,
     `Framework:       ${detected.stack.framework || '—'}`,
     `Deployment:      ${detected.stack.deployment || '—'}`,
+    `Worktree env:    ${(detected.stack.env_files || []).join(', ') || '—'}`,
   ]);
 
   if (opts.nonInteractive) {

package/src/commands/update.js

@@ -1285,12 +1285,16 @@ async function update(options = {}, unknownArgs = []) {
             const missingGit = Object.keys(tpl.git || {})
               .filter((k) => !(k in (cur2.git || {})));
             // Scalar top-level stack.* keys — e.g. stack.database,
-            // stack.auth_provider, stack.framework, stack.deployment (strings) and
-            // stack.schema_deploy_from_trunk_only (boolean, since v4.33.0). Sub-object
-            // keys (charting, animation, testing) are intentionally skipped:
-            // their drift is handled by individual sub-prompts in configure.
+            // stack.auth_provider, stack.framework, stack.deployment (strings),
+            // stack.schema_deploy_from_trunk_only (boolean, since v4.33.0) AND
+            // top-level ARRAY keys (stack.env_files, v4.46.0 —
+            // `typeof [] === 'object'`, so it needs Array.isArray to be caught;
+            // without it the new key would silently never be asked). Sub-OBJECT
+            // keys (charting, animation, testing) stay skipped — Array.isArray({})
+            // is false, so they are not flagged — their drift is handled by
+            // individual sub-prompts in configure.
             const missingStack = Object.keys(tpl.stack || {})
-              .filter((k) => ['string', 'boolean'].includes(typeof tpl.stack[k]))
+              .filter((k) => ['string', 'boolean'].includes(typeof tpl.stack[k]) || Array.isArray(tpl.stack[k]))
               .filter((k) => !(k in (cur2.stack || {})));
             // Top-level nested config namespaces (e.g. `graph:` since v4.21.0).
             // Unlike `lsp:` (which propagates only via its `has_lsp_layer` flag),