baldart 4.45.0 → 4.47.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.47.0] - 2026-06-16
+
+**`/new`'s orchestrator context economy is re-aimed at its real driver — turn count — and the user-visible Progress Bar + native Task spine are removed.** Telemetry of two real 8-card batches (FEAT-0028/0029 on a consumer) showed the orchestrator paying ~285M `cache_read`: 613 turns each replaying a ~490k-token accumulated context (growing toward ~800k), so total cost ≈ **turn count × accumulated context**. A 3-lens **adversarial review before implementation** refuted the obvious diagnoses: the static prefix is only ~77k (not the ~225k first assumed — context is ~86% *accumulated*, not static); narration prose is only ~7% of the fuel; and the existing § "Context economy" (bulk-content-inline) rule targets a channel that totals only ~119k cumulatively. The measurement reviewer surfaced the actual missed lever — **0 of 274 tool turns batched any calls, and ~55% of turns carried no tool call at all** — and the correctness + prior-art reviewers established that delegating bookkeeping out of the orchestrator is a previously-trodden trap (v4.15.0 reverted a Write-from-memory tracker flush; the tracker is the recovery SSOT; `card_status: DONE` needs orchestrator-side disk re-read; the weak-subagent fabrication precedent applies). What survived: (1) a new turn-economy HARD RULE (batch independent tool calls; no narration-only turns; never poll/wait), and (2) since the Progress Bar + Task spine are pure *mirrors* of the internal tracker (recovery reads the tracker, never the spine), removing them is correctness-safe and eliminates ~45 dedicated visibility turns (~8% of a batch's `cache_read`, guaranteed, not batching-dependent). **MINOR** (skill behaviour change; **no new `baldart.config.yml` key** ⇒ schema-change propagation rule N/A; no removed agent/command/skill/routine).
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — replaced the `## Progress Visibility (MANDATORY)` section (native Task spine + transition Progress Bar + Phase→ledger mapping) with `## State surface — the tracker only`: the internal `/tmp/batch-tracker-*.md` is now the SINGLE state surface (it was already the recovery SSOT; the spine/bar were never read by recovery). Added a second HARD RULE to § "Context economy" — **"turn count is the multiplier"** — instructing the orchestrator to (1) batch independent tool calls into one message, (2) never emit a narration-only turn, (3) never poll/wait on background work. The § "Context Tracking" mirror bullet and the § "Routing" core-invariant list are reconciled.
+- **`framework/.claude/skills/new/references/{setup,implement,commit,team-mode,final-review,merge-cleanup}.md`** — every `**→ Visibility**: TaskUpdate … / emit a Progress Bar` step is removed; the underlying *state* writes (card `IN_PROGRESS` claim at implement.md 2b, `card_status: DONE (verified)` at commit.md 29 / team D.6) are **preserved** (they are correctness, not visibility) and now explicitly note the tracker is the only surface. Pre-flight no longer creates a Task spine (setup.md step 2b).
+
+## [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.47.0

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

@@ -129,80 +129,25 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
   - **card_status: DONE (verified)** — confirms the backlog YAML was updated and re-read to verify
 - **When blocked**: log the blocker in `## Issues & Flags`.
 - **On context recovery**: if you ever feel lost or after context compaction, IMMEDIATELY read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to restore your state.
-- **Mirror every transition to the user (MANDATORY)**: this tracker file is internal — the user does NOT see it. Every transition you log here MUST also be reflected in the **two user-visible surfaces** defined in § "Progress Visibility": the native **Task spine** (TaskUpdate) and, at transition boundaries, the **Progress Bar**. The tracker is the recovery SSOT; the Task spine + Progress Bar are its live mirror.
+- **The tracker is internal and is the ONLY state surface** (since v4.47.0 — see § "State surface — the tracker only"): the user does NOT see it, and there is no separate user-visible mirror to keep in sync. Do NOT spend a dedicated turn restating a transition to the user (no TaskUpdate, no Progress-Bar block) — surface progress only as a short prose line folded into a turn you are already taking for real work (§ "Context economy" turn-count rule).
 
 ---
 
-## Progress Visibility (MANDATORY)
+## State surface — the tracker only
 
-The `/tmp/batch-tracker-*.md` file is your **internal** recovery SSOT — the user never sees it. Because `/new` runs largely autonomously (YOLO mode, long stretches of agent spawns), the user otherwise has no idea which phase is running, which wave of the team mode is in flight, or which gate was just resolved vs skipped. This section defines the **two user-visible surfaces** that fix that. They are the live mirror of the tracker; keeping them in sync is non-negotiable.
+`/new` keeps a **single** state surface: the internal `/tmp/batch-tracker-<FIRST-CARD-ID>.md`
+recovery SSOT (§ "Context Tracking"). There is **no separate user-visible mirror**. The Progress
+Bar markdown block and the per-transition native Task spine (TaskCreate/TaskUpdate) were **removed
+for context economy (v4.47.0)**: every standalone TaskUpdate / Progress-Bar emission was its own
+orchestrator turn paying a full accumulated-context replay (~490k tokens median, measured ~8% of a
+batch's cache_read) for zero correctness value — the tracker already holds the authoritative state,
+and recovery (§ "Context recovery protocol") reads the tracker, never the Task spine.
 
-> **HARD RULE — visibility.** (1) Maintain the native **Task spine** via TaskCreate/TaskUpdate. (2) Emit the **Progress Bar** at every transition boundary (defined below). Both mirror the tracker. Failing to update either after a transition is a protocol violation.
-
-### A. Task spine — native TaskCreate/TaskUpdate (the always-visible panel)
-
-The native task list is what Claude Code renders as a **persistent, always-visible todo panel** (this is exactly how `/prd` gets its beloved todo list — see `framework/.claude/skills/prd/SKILL.md` HARD RULE 4). Keep it **coarse**: one task per card plus a few batch-level framing tasks. Do NOT create a task per phase (that buries the overview).
-
-**When to create (once):** right after Pre-flight has resolved the execution mode (sequential vs team) and, in team mode, the wave layout (`execution_strategy.groups[].level`) — because only then do you know the wave label for each card. Create, in this order:
-
-1. `Pre-flight` — framing task (already in progress by the time you create the spine; mark it `in_progress` immediately and `completed` as soon as the worktree is ready).
-2. One task **per card**, in queue order. Subject:
-   - **team mode** (wave-labelled): `Wave <level> · <CARD-ID> — <title>` (e.g. `Wave 1 · FEAT-0502 — Add merchant filter`).
-   - **sequential mode**: `<CARD-ID> — <title>` (no wave prefix).
-3. `Final review` — framing task.
-4. `Merge & cleanup` — framing task.
-
-**State transitions (TaskUpdate):**
-
-| Task | → `in_progress` | → `completed` |
-|------|-----------------|---------------|
-| `Pre-flight` | at spine creation | worktree ready (end of Pre-flight) |
-| card task | **Phase 1 step 2b** (claim — when you set the card `status: IN_PROGRESS`) | **Phase 4 step 28** (after commit + `card_status: DONE (verified)`) |
-| `Final review` | start of Final Review (F.1) | Final Review complete (fixes applied, build green) |
-| `Merge & cleanup` | start of Phase 6 | end of Phase 6c |
-
-**Live sub-state in the subject (optional but encouraged):** while a card task is `in_progress`, you MAY append the current phase to its subject so the panel shows live movement between Progress Bar emissions — e.g. `Wave 1 · FEAT-0502 — Add merchant filter · Phase 3.7 Codex 🔄`. Strip the suffix when the card completes.
-
-In team mode the cards of a wave run in parallel: set ALL of a wave's card tasks `in_progress` when that wave's coders are spawned (Step B), and complete each as its per-card pipeline reaches Phase 4 (team Step D.5/D.6).
-
-### B. Progress Bar — markdown, at transition boundaries
-
-Append this block to your message **at the heavy transition boundaries only** (NOT on every message, and NOT on every intra-card phase change — that accumulates markdown across long autonomous runs; per § "Context economy"). A **heavy transition boundary** is any of: a **card change**, a **wave change**, **any gate decision** (resolved or skipped), and every `AskUserQuestion` / STOP. **Intra-card phase movement** (e.g. Phase 2 → 2.5 → 2.55 within the same card, with no gate decision) is shown via the **Task spine live sub-state** (TaskUpdate, § A above) — NOT by re-emitting this full markdown block each phase.
-
-```
----
-📋 **Progresso /new: <batch-id>** — modalità <sequential|team> · Wave <X>/<Y>
-
-| Card | Wave | Fase corrente | Stato |
-|------|------|---------------|-------|
-| FEAT-0501 | 0 | Phase 4 Commit | ✅ |
-| FEAT-0502 | 1 | Phase 3.7 Codex | 🔄 |
-| FEAT-0503 | 1 | — | ⬜ |
-
-Gate ledger (card corrente): 2.5b AC-Closure ✅ · 2.55 Simplify ✅ · 2.6 E2E ⏭️ (backend-only) · 3 Doc ⏭️ (light, no-doc-diff→Final) · 3.5 QA ⏭️ (balanced→Final) · 3.7 Codex 🔄
-Prossimo passo: <cosa succede dopo>
-```
-
-- Legend: `⬜ da fare · 🔄 in corso · ✅ risolto · ⏭️ skippato`.
-- The `Wave` column and the `Wave <X>/<Y>` header are present in **team mode** only; in sequential mode drop the column and write `modalità sequential` with no wave counter.
-- The **Gate ledger** line shows the current card's per-card gates (see § C for which). Each entry is `<gate> <state>`; a skipped entry MUST carry its reason **verbatim from the enumerated Gate-table / fast-lane skip reasons** — e.g. `IS_TRIVIAL`, `review_profile=light`, `backend-only diff`, `features.has_e2e_review:false`, `balanced→Final`, `holistic_audit provenance`. **Never invent a reason.** A ledger entry reading `⏭️ (time budget)` / `(to save tokens)` / any model-invented constraint is itself a protocol violation (see the top-of-file "NO PHASE SKIP FOR PERCEIVED TIME" clause) — the ledger exists to make skips auditable, not to license them.
-
-### C. Phase → ledger mapping
-
-These are the per-card gates tracked in the Gate ledger line (the rest of the pipeline — Phase 1 context, Phase 2 implement, Phase 4 commit — is shown in the table's "Fase corrente" column, not the ledger):
-
-| Ledger entry | Phase | Skipped when (enumerated reason) |
-|--------------|-------|----------------------------------|
-| `2.5b AC-Closure` | Phase 2.5b | never (BLOCKING, unconditional) |
-| `2.55 Simplify` | Phase 2.55 | `IS_TRIVIAL` |
-| `2.6 E2E` | Phase 2.6 | `features.has_e2e_review:false`, backend-only diff, or card type ∈ {backend/api/db/infra/docs/chore/config} |
-| `3 Doc` | Phase 3 | `review_profile=light` AND no doc files in diff → deferred to Final F.3 |
-| `3.5 QA` | Phase 3.5 | `skip`/`light` (tests already ran Phase 2), or `balanced`→Final (unless Step-A escalation) |
-| `3.7 Codex` | Phase 3.7 | `IS_TRIVIAL` only (otherwise unconditional; `light`/`full` is depth, not skip) |
-
-In **team mode** the same gates map to the per-card team sub-steps (D.3a AC-Closure, D.3b Simplify, D.3c E2E, D.4 QA, D.4a/D.2 doc, D.4b Codex) — track them identically. The pre-flight cross-card Codex check (Step 3d) and plan-auditor grounding (Phase 1 step 4) are batch/card-setup gates: surface their resolve/skip in the `Prossimo passo` line or a one-off ledger note, not as recurring per-card rows.
-
----
+> **HARD RULE — no dedicated visibility turns.** Do NOT spend a turn (a TaskUpdate, a Progress-Bar
+> markdown block, or a narration-only message) whose sole purpose is to restate progress. Surface
+> progress to the user ONLY as a short natural-prose line **folded into a turn you are already
+> taking** for real work — per § "Context economy" → turn-count rule. `STOP` / `AskUserQuestion`
+> moments are surfaced as before (they carry a real decision, not a status restatement).
 
 ## Context economy (MANDATORY)
 
@@ -241,6 +186,30 @@ baselines. Keep that bulk on disk and pass **paths**, not bodies.
 > nor what the orchestrator is allowed to read at a decision point — only that bulk arrives via a
 > path the consumer opens itself, not via the orchestrator's own context.
 
+> **HARD RULE — turn count is the multiplier (this is the dominant cost).** Measurement of real
+> batches shows the bulk-content rule above is necessary but NOT where most tokens go: the
+> orchestrator's accumulated context (~490k tokens median, growing toward ~800k on long batches) is
+> **replayed in full on EVERY turn** via `cache_read`. So total cost ≈ **turn count × accumulated
+> context** — and the cheapest turn (a lone `cd`, a single TaskUpdate, a one-line narration) pays the
+> SAME ~490k replay as the most expensive one. A measured 8-card batch ran **613 orchestrator turns,
+> of which 0 batched any tool calls and ~55% carried no tool call at all.** Cut turns:
+> 1. **Batch independent tool calls into ONE message.** Whenever you need ≥2 tool calls with no data
+>    dependency between them — several `Read`s, a `cd` plus the command that follows it, `Edit`s to
+>    different files, a status `Edit` to the tracker alongside the next real action — emit them in a
+>    **single assistant message**, not one-per-turn. A run that issues 270 tool calls one-per-turn
+>    pays ~270 full-context replays; batched ~3-for-1 it pays ~90. Never split independent mechanical
+>    calls across turns "for clarity."
+> 2. **No narration-only turns.** Never emit a turn whose only content is a progress recap, a
+>    "now I will…" preamble, or a status restatement. If a status note matters, fold it into the same
+>    message as the next tool call. (Per § "State surface" the tracker is the only state surface — and
+>    you write it via batched `Edit`s, never narrate it.)
+> 3. **Never poll or wait.** Background subagents and background `Bash` re-invoke you automatically on
+>    completion — end your turn after spawning; never `sleep N; echo "waiting…"` (already stated for
+>    team mode in `references/team-mode.md` — it applies to every barrier in both modes).
+>
+> These rules reduce the *number* of replays; the bulk-content rule above reduces the *size* of each.
+> Both compound — apply them together.
+
 ---
 
 ## Toolchain gates
@@ -268,7 +237,7 @@ Reference modules cite this section as `§ "Toolchain gates"`.
 sistema, ri-letto a OGNI turno. Per non pagare 60k+ token di istruzioni di fase a
 ogni turno, il dettaglio passo-passo di ogni fase vive in un **modulo `references/<x>.md`**
 caricato on-demand. Questo file (il core) tiene solo gli invarianti cross-fase
-(Context Tracking, Progress Visibility, § "Context economy", § "Toolchain gates",
+(Context Tracking, State surface, § "Context economy", § "Toolchain gates",
 Agent Routing, QA Profile, Trivial fast-lane, Risk-signal detector, Fix Application
 Log) + questa mappa di navigazione.
 

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

@@ -35,7 +35,7 @@
     c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
-29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**. **→ Visibility**: TaskUpdate this card's spine task → `completed` (strip any live phase suffix) and emit a Progress Bar (card change) per § "Progress Visibility".
+29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`** — the tracker is the only state surface (§ "State surface — the tracker only"); do not also emit a TaskUpdate or Progress-Bar turn for the transition. If you surface the card completion to the user at all, do it as a short prose line folded into the commit turn, never a dedicated turn.
 
 ### Sub-agent failure protocol (since v3.28.3)
 

package/framework/.claude/skills/new/references/final-review.md

@@ -42,7 +42,7 @@ Once ALL cards are committed in the worktree:
 
 ### Step F.1 — Resolve scope
 
-**→ Visibility (batch transition)**: all cards are committed. TaskUpdate `Final review` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark `Final review` → `completed` when F.5 finishes (fixes applied, build green).
+(All cards are committed; the batch now enters Final Review. No visibility emission — the internal tracker is the only state surface, see SKILL.md § "State surface — the tracker only". Record the Final-Review start/finish in the tracker only.)
 
 1. **Read the tracker file** to get the full picture: card IDs, files changed, commit hashes.
 2. Gather git evidence in the worktree:

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

@@ -8,7 +8,7 @@
    - Read that card's backlog YAML and check its `status` field.
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly. **The card status is NOT written until this gate passes** — so a HALT leaves the card untouched (no stale `IN_PROGRESS` for the next run to mis-read).
    - If `DONE` (or the user chose "proceed anyway") → continue.
-2b. **Claim** — only now set the card status to `IN_PROGRESS` and assign yourself. **→ Visibility**: TaskUpdate this card's spine task → `in_progress`, and emit a Progress Bar (card change) per § "Progress Visibility".
+2b. **Claim** — only now set the card status to `IN_PROGRESS` (in the backlog YAML / tracker) and assign yourself. This is a state write, not a visibility emission — do not also spend a TaskUpdate / Progress-Bar turn (§ "State surface — the tracker only").
 2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
 3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. Likewise, when `features.has_code_graph: true`, the architect uses the Graphify code graph for structural/relational lookups (ambient flag) per `agents/code-graph-protocol.md`. The orchestrator does NOT propagate either flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.)
 3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.

package/framework/.claude/skills/new/references/merge-cleanup.md

@@ -4,7 +4,7 @@
 
 ## Phase 6 — Post-batch merge & cleanup (delegated to worktree-manager skill)
 
-**→ Visibility (batch transition)**: TaskUpdate `Merge & cleanup` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark it → `completed` at the end of Phase 6c (merge done, worktree removed, workspace reconciled).
+(The batch now enters Merge & cleanup. No visibility emission — the internal tracker is the only state surface, see SKILL.md § "State surface — the tracker only". Record merge/cleanup completion in the tracker only.)
 
 After the final review passes AND all cards are committed in the worktree, delegate the entire merge and cleanup to the **worktree-manager** skill (`/mw` in programmatic mode):
 

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

@@ -182,7 +182,7 @@
 
    When `mode == sequential`, the per-card pipeline below runs exactly as documented. The `execution_strategy.groups` levels are simply ignored. When `mode == team`, skip the per-card pipeline and follow the **Team Mode** section at the end of this document.
 
-   **→ Create the Task spine now.** The execution mode and (in team mode) the wave layout are resolved — create the native Task spine per § "Progress Visibility" A: `Pre-flight` (→ `in_progress`) + one task per card (wave-labelled in team mode) + `Final review` + `Merge & cleanup`. Emit the first Progress Bar with this batch's table. Mark `Pre-flight` → `completed` at the pre-flight resume (step 6d), once both background ops have returned and the consolidated tracker flush is written.
+   (No user-visible Task spine / Progress Bar is created — the internal tracker is the only state surface; see SKILL.md § "State surface — the tracker only".)
 
 3d. **Codex batch cross-card grounding check** (background — launched together with the worktree-setup subagent in step 4, then a single barrier in step 5)
 
@@ -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.
@@ -322,7 +324,6 @@
       - `## Worktree` — path / branch / slug / port, plus `Created:` = **the subagent block's `created_at`** (worktree-creation time, NOT resume time, so Phase 8's `cycle_time_mins` still spans the build window). On the **4a2 resume** path, `Created:` = the registry entry's `createdAt`; on the **4d inline fallback**, stamp `date -u +%Y-%m-%dT%H:%M:%SZ` at creation. (Never leave `Created:` empty — `cycle_time_mins` anchors on it.)
       - `## Cross-Card Conflicts (Codex)` — distilled findings (the 3d skip-decision already wrote the `SKIPPED`/`RUN — reason` line; append the distilled findings on the RUN path, nothing to add on SKIP).
       - In team mode: `## Team Mode` + `## Parallel Groups` (per team-mode.md).
-      `## Execution Mode` was already written at step 3c (it must exist before the Task spine) — do NOT rewrite it here. **Rationale**: pre-flight is idempotent and cheap to redo (step 4a2's git pre-check guards worktree re-creation), so the data sections do not need mid-flight persistence; per-phase incremental writes resume for card execution, where mid-phase recovery actually matters. The file already exists (the skeleton was created at batch start per § Context Tracking; Phase 0 wrote `## Phase 0`) — backfill, do NOT re-create.
-   d. **→ Visibility**: mark the `Pre-flight` Task spine entry → `completed` and emit the first wave's Progress Bar.
+      `## Execution Mode` was already written at step 3c — do NOT rewrite it here. **Rationale**: pre-flight is idempotent and cheap to redo (step 4a2's git pre-check guards worktree re-creation), so the data sections do not need mid-flight persistence; per-phase incremental writes resume for card execution, where mid-phase recovery actually matters. The file already exists (the skeleton was created at batch start per § Context Tracking; Phase 0 wrote `## Phase 0`) — backfill, do NOT re-create.
 
 ---

package/framework/.claude/skills/new/references/team-mode.md

@@ -57,7 +57,7 @@ its `arch_baseline_path` at this file, so the review reuses the group baseline i
 
 #### Step B: Spawn parallel coder agents
 
-**→ Visibility (wave change)**: this is a new wave starting. TaskUpdate ALL of this group's card spine tasks → `in_progress`, and emit a Progress Bar with the new `Wave <X>/<Y>` header per § "Progress Visibility".
+(No visibility emission on wave change — the internal tracker is the only state surface; see SKILL.md § "State surface — the tracker only". Record the wave start in the tracker only.)
 
 For each card in the current group, spawn a coder agent using the Agent tool. ALL agents for the group MUST be spawned in a **SINGLE message** (multiple Agent tool calls) to run truly in parallel.
 
@@ -278,8 +278,7 @@ After ALL agents in the group complete successfully:
    a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`, add implementation notes (NEVER include `[USER-APPROVED DEFERRAL]` lines that didn't actually pass through D.3a's gate).
    b. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry.
    c. Stage the updated YAML and include it in the card's commit (or as an immediate follow-up commit).
-   d. Log in tracker: `card_status: DONE (verified)` for each card.
-   e. **→ Visibility**: TaskUpdate each card's spine task → `completed` (strip any live phase suffix) as it reaches DONE here.
+   d. Log in tracker: `card_status: DONE (verified)` for each card — the tracker is the only state surface (§ "State surface — the tracker only"); do not emit a TaskUpdate turn per card.
    Note: Phase 6b (Status Reconciliation) will catch any card missed here, but aim for zero misses.
 
 #### Step D coverage assertion (MANDATORY end-of-group check)
@@ -302,8 +301,7 @@ A missing entry means a sub-step was skipped. An entry whose value is a **`revie
 After committing all cards in the group:
 1. Update tracker: move group to done, log all results per card.
 2. **PURGE**: forget all implementation details, review findings, architect context.
-3. **→ Visibility**: emit a Progress Bar reflecting the wave boundary (this wave done; next `Wave <X+1>/<Y>` pending) per § "Progress Visibility".
-4. Move to the next pending group (Step A again).
+3. Move to the next pending group (Step A again).
 
 ### Sequential fallback within team mode
 

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.47.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),