baldart 3.41.0 → 4.0.0

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

@@ -4,7 +4,7 @@ description: >
   Manage fully independent git worktrees for parallel coding agents.
   Commands: /nw (new worktree) creates an isolated workspace with its own
   node_modules, .next cache, and dev server port; /mw (merge worktree) commits,
-  pushes, creates PR to develop, merges, and cleans up; /lw (list worktrees)
+  pushes, creates PR to the trunk branch (git.trunk_branch), merges, and cleans up; /lw (list worktrees)
   shows status of all active worktrees; /cw (cleanup worktrees) removes stale
   or already-merged worktrees without the full PR flow.
   Also used programmatically by /new orchestrator for batch card worktree ops.
@@ -15,8 +15,10 @@ description: >
 # Worktree Manager
 
 **Project Context (resolved from `baldart.config.yml`)**:
-- `git.merge_strategy` — `pr` (default, GitHub PR via `gh`) or `local-push` (direct fast-forward to `origin/develop`). Drives `/mw` step 4c.
+- `git.trunk_branch` — the integration trunk branch (resolved value, default autodetected). Every worktree branches from `origin/<git.trunk_branch>` and merges back into it. NEVER hardcode `develop` or `main`.
+- `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.
 - Protocol reference: `framework/agents/project-context.md`. Skills must ASK when a needed key is missing — never assume.
 
 **IMMEDIATE EXECUTION**: When invoked via `/nw`, `/mw`, `/lw`, or `/cw`, do NOT explain the process. Start executing the matching command flow immediately:
@@ -61,11 +63,11 @@ What docs mode SKIPS vs the standard flow:
 - No build / lint / tsc gates at merge time
 
 What docs mode KEEPS:
-- Pre-flight `git fetch origin develop` (read-only on the main repo).
-- `git worktree add` branched from `origin/develop`.
+- Pre-flight `git fetch origin <git.trunk_branch>` (read-only on the main repo).
+- `git worktree add` branched from `origin/<git.trunk_branch>`.
 - Registry entry with `kind: "docs"` so `/lw` and `/cw` can list and clean docs worktrees alongside code worktrees.
 - Safety commit at merge time (uncommitted files are never lost).
-- Rebase onto `origin/develop` before merging (prevents PR/FF conflicts).
+- Rebase onto `origin/<git.trunk_branch>` before merging (prevents PR/FF conflicts).
 - The configured `git.merge_strategy` (`pr` or `local-push`).
 - Cleanup of worktree + local branch + remote branch after merge.
 
@@ -108,8 +110,18 @@ 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.
+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
+fi
+
 # 1. Pre-flight — read-only fetch, NEVER touches main repo HEAD
-git fetch origin develop
+git fetch origin "$TRUNK"
 
 # 2. Duplicate check — read registry; if an entry with the same slug AND kind=docs
 #    exists, return the existing { path, branch, kind } instead of creating a new
@@ -120,16 +132,21 @@ git fetch origin develop
 # 3. Create the worktree. The path returned MUST be ABSOLUTE — Claude Code's
 #    Write/Edit require absolute paths, and downstream skills (/prd, ui-design,
 #    prd-card-writer) interpolate this path verbatim.
+#    SLUG must be kebab-case + deterministic (R8): the same slug always maps to
+#    the same worktree path, so a resumed /prd run finds the existing worktree.
 SLUG="<slug>"
 BRANCH_PREFIX="${branchPrefix:-prd/}"
 BRANCH="${BRANCH_PREFIX}${SLUG}"
-WORKTREE_REL=".worktrees/prd-${SLUG}"
+WORKTREE_REL=".worktrees/prd-${SLUG}"      # deterministic: derived from slug only, no timestamp
 WORKTREE_PATH="$MAIN_ROOT/$WORKTREE_REL"   # absolute, anchored to main repo root
-git -C "$MAIN_ROOT" worktree add "$WORKTREE_REL" -b "$BRANCH" origin/develop
+git -C "$MAIN_ROOT" worktree add "$WORKTREE_REL" -b "$BRANCH" "origin/$TRUNK"
 
 # 4. Registry entry — kind: "docs", port: null, buildVerified: null
 #    Same registry file (.worktrees/registry.json) as code worktrees.
 #    The `path` field MUST hold $WORKTREE_PATH (absolute), not $WORKTREE_REL.
+#    R6: persist $MAIN_ROOT, slug, branch AND the resolved trunk on the entry
+#    (fields: path, slug, branch, trunkBranch) so every later consumer reads them
+#    from the registry with a presence guard — never relies on in-context vars.
 ```
 
 **Registry entry shape for docs worktrees:**
@@ -141,6 +158,8 @@ git -C "$MAIN_ROOT" worktree add "$WORKTREE_REL" -b "$BRANCH" origin/develop
   "groupParent": null,
   "slug": "menu-nutritional-info",
   "branch": "prd/menu-nutritional-info",
+  "trunkBranch": "develop",
+  "mainRoot": "/abs/repo-root",
   "path": "/abs/.worktrees/prd-menu-nutritional-info",
   "port": null,
   "kind": "docs",
@@ -177,6 +196,19 @@ Output:
 **Steps (run exactly these, nothing else):**
 
 ```bash
+# Presence guard (R6): $WORKTREE_PATH and the resolved $TRUNK MUST be read from
+# the registry entry (fields path / trunkBranch) and be non-empty before any op.
+if [ -z "$WORKTREE_PATH" ]; then
+  echo "ERROR: \$WORKTREE_PATH unset — read it from the registry entry before mw-docs." >&2
+  exit 1
+fi
+# If $TRUNK is unset, read the `trunkBranch` field from this worktree's registry
+# entry in .worktrees/registry.json (do NOT assume 'develop').
+if [ -z "$TRUNK" ]; then
+  echo "ERROR: trunk branch unresolved — read trunkBranch from the registry entry (do NOT assume 'develop')." >&2
+  exit 1
+fi
+
 cd "$WORKTREE_PATH"
 
 # 1. Safety commit (MANDATORY — same as /mw step 3, never skippable).
@@ -191,18 +223,17 @@ cd "$WORKTREE_PATH"
 #      - ${paths.references_dir}/project-status.md (if updated by Step 7)
 #    NEVER `git add .` or `git add -A`. NEVER `git stash` (see Safety Rules).
 
-# 2. Rebase onto latest develop. Reuses the /mw step 4b conflict-resolution
-#    table (additive auto-strip for docs/yaml/jsonl-in-docs-metrics; abort on
-#    structured registries when validation fails; abort on code/tests/fixtures).
+# 2. Rebase onto the latest trunk branch ($TRUNK = git.trunk_branch). Reuses the
+#    /mw step 4b conflict-resolution table (additive auto-strip for
+#    docs/yaml/jsonl-in-${paths.metrics}; abort on structured registries when
+#    validation fails; abort on code/tests/fixtures).
 #
-#    IMPORTANT — NO `git stash` in mw-docs. The safety commit in step 1
-#    above guarantees a clean working tree, so the stash logic at the top of
-#    /mw step 4b ("stash dirty files before rebase, pop after") is a no-op
-#    for mw-docs and must be SKIPPED. Running `git stash push` from a
+#    NO `git stash` in mw-docs (or anywhere in a worktree). The safety commit in
+#    step 1 above guarantees a clean working tree. Running `git stash push` from a
 #    worktree violates the Safety Rule "NEVER use git stash in worktrees"
 #    (refs/stash is shared across all worktrees via git.commondir — see the
-#    FEAT-0522 incident note). Two parallel mw-docs runs that both stash
-#    would race on the shared stash list and could pop into the wrong tree.
+#    FEAT-0522 incident note). Two parallel runs that both stash would race on the
+#    shared stash list and could pop into the wrong tree.
 #
 #    Direct rebase, no stash. If the working tree is unexpectedly dirty here
 #    (someone wrote between step 1 and step 2), STOP and report — a second
@@ -214,14 +245,14 @@ if [ -n "$DIRTY" ]; then
   echo "Investigate — never stash to recover (refs/stash shared across worktrees)." >&2
   exit 1
 fi
-git -C "$WORKTREE_PATH" fetch origin develop
-git -C "$WORKTREE_PATH" rebase origin/develop
+git -C "$WORKTREE_PATH" fetch origin "$TRUNK"
+git -C "$WORKTREE_PATH" rebase "origin/$TRUNK"
 # (apply /mw 4b conflict-resolution table if rebase reports conflicts)
 
-# 3. Land on develop — reuse /mw step 4c verbatim. Read git.merge_strategy from
-#    baldart.config.yml. NEVER `git checkout develop` on the main repo.
+# 3. Land on trunk — reuse /mw step 4c verbatim. Read git.merge_strategy from
+#    baldart.config.yml. NEVER `git checkout <trunk>` on the main repo.
 #    - pr        → gh pr create + gh pr merge --merge --delete-branch
-#    - local-push → git push origin <branch>:develop (fast-forward only)
+#    - local-push → git push origin <branch>:$TRUNK (fast-forward only)
 #
 #    Note: many consumers prefer `local-push` for docs worktrees specifically,
 #    because a PRD is rarely worth a GitHub PR roundtrip. The CLI does not
@@ -232,8 +263,8 @@ git -C "$WORKTREE_PATH" rebase origin/develop
 #    Skip /mw step 5 (post-merge `npm run build`) — docs worktrees have nothing
 #    to build.
 
-# 5. Sync local develop ref — reuse /mw "Common" block: ff-only pull when main
-#    repo HEAD is already develop; otherwise just fetch.
+# 5. Sync local trunk ref — reuse /mw "Common" block: ff-only pull when main
+#    repo HEAD is already $TRUNK; otherwise just fetch.
 
 # 6. Remove the registry entry for this worktree.
 ```
@@ -248,7 +279,7 @@ can investigate. Cleanup runs only after a successful merge.
 
 The merge path depends on `git.merge_strategy` in `baldart.config.yml`:
 - `pr` (default, since v3.4.0): merge via `gh pr create` + `gh pr merge`. `prNumber` is the PR number, `mergeCommit` is the SHA returned by the GitHub merge API.
-- `local-push` (since v3.9.0): direct fast-forward push of the rebased feature branch to `origin/develop` — no PR, no `gh`. `prNumber` is `null`, `mergeCommit` is the local SHA of the feature branch tip.
+- `local-push` (since v3.9.0): direct fast-forward push of the rebased feature branch to `origin/<git.trunk_branch>` — no PR, no `gh`. `prNumber` is `null`, `mergeCommit` is the local SHA of the feature branch tip.
 
 Neither path runs `git checkout` / `git switch` / `git branch` on the main repo. The orchestrator can branch on `strategy` if it needs PR linking (only meaningful in `pr` mode).
 
@@ -276,6 +307,8 @@ All worktree operations read/write `.worktrees/registry.json`:
       "groupParent": "FEAT-0200",
       "slug": "menu-ranking",
       "branch": "feat/FEAT-0200-menu-ranking",
+      "trunkBranch": "develop",
+      "mainRoot": "/absolute/path",
       "path": "/absolute/path/.worktrees/feat-FEAT-0200-menu-ranking",
       "port": 3001,
       "createdAt": "2026-03-09T10:00:00Z",
@@ -289,6 +322,8 @@ All worktree operations read/write `.worktrees/registry.json`:
 - `card`: primary card ID (first card or group parent), or `null` for slug-only worktrees
 - `cards`: all card IDs sharing this worktree (for batches), or `[]` for slug-only
 - `groupParent`: from backlog card `group.parent` field, or `null` for standalone/slug-only
+- `trunkBranch`: the resolved `git.trunk_branch` this worktree was created from (R6 — persisted so `/mw`/`/cw` never re-guess or assume `develop`)
+- `mainRoot`: absolute path of the main repo root (R6 — persisted so `$MAIN` is read from the registry, not from in-context state that does not survive compaction)
 - `buildVerified`: true if `npm run build` passed after setup
 
 Create the file if it doesn't exist. Update it on every `/nw`, `/mw`, `/cw` operation.
@@ -305,14 +340,26 @@ Supports three modes:
 ### 1. Pre-flight checks
 
 ```bash
-# Fetch latest develop from remote — read-only, does NOT touch the main repo's HEAD.
-# We branch the new worktree from `origin/develop` directly (step 3), so we never
-# need to checkout develop on the main repo. This is the absolute rule:
+# Resolve $MAIN (main repo root) and $TRUNK (git.trunk_branch) up front, and
+# 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)"
+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
+fi
+
+# Fetch latest trunk from remote — read-only, does NOT touch the main repo's HEAD.
+# We branch the new worktree from `origin/<trunk>` directly (step 3), so we never
+# need to checkout the trunk on the main repo. This is the absolute rule:
 # /nw must not run `git checkout`, `git switch`, `git checkout -b`, or
 # `git branch` on the main repo (it's shared across parallel terminals; many
 # consumer projects declare this as a hard rule in CLAUDE.md and the classifier
 # will block the call preemptively).
-git fetch origin develop
+git fetch origin "$TRUNK"
 ```
 
 (There is no need to check `git status --porcelain` on the main repo here — we
@@ -347,22 +394,24 @@ Branch name: `feat/<CARD-ID>-<slug>` (with card) or `feat/<slug>` (slug-only). U
 
 ### 3. Create the worktree
 
-Base the new worktree on `origin/develop` (the remote tip we just fetched in step 1) rather than the local `develop` branch — that way we never need the local `develop` to be checked out or up to date on the main repo.
+Base the new worktree on `origin/<$TRUNK>` (the remote tip we just fetched in step 1) rather than the local trunk branch — that way we never need the local trunk to be checked out or up to date on the main repo.
+
+The worktree path is **deterministic** (R8): derived from the card ID + kebab-case slug only, never a timestamp — so a resumed run resolves to the same path and the duplicate check in step 1 is meaningful.
 
 ```bash
 # With card ID:
 WORKTREE_PATH=".worktrees/feat-<CARD-ID>-<slug>"
-git worktree add "$WORKTREE_PATH" -b "feat/<CARD-ID>-<slug>" origin/develop
+git worktree add "$WORKTREE_PATH" -b "feat/<CARD-ID>-<slug>" "origin/$TRUNK"
 
 # Slug-only (no card):
 WORKTREE_PATH=".worktrees/feat-<slug>"
-git worktree add "$WORKTREE_PATH" -b "feat/<slug>" origin/develop
+git worktree add "$WORKTREE_PATH" -b "feat/<slug>" "origin/$TRUNK"
 ```
 
 ### 3b. Sync untracked backlog cards from main repo
 
 Backlog cards created during `/prd` sessions may exist as untracked files in the main repo
-but are NOT on `develop` yet. The worktree (branched from develop) won't have them.
+but are NOT on the trunk branch yet. The worktree (branched from the trunk) won't have them.
 
 ```bash
 MAIN_ROOT="$(git -C "$WORKTREE_PATH" rev-parse --show-superproject-working-tree 2>/dev/null || pwd)"
@@ -432,8 +481,8 @@ if [ -n "$HOOK_SRC" ]; then
   case "$ACTIVE" in
     "$HOOK_SRC"|"$HOOK_SRC"/*|.husky/_) : ;;  # active dir serves the versioned hooks (incl. husky v9 .husky/_)
     *)
-      echo "⚠️  WARNING: git hooks INATTIVI — gli hook versionati sono in '$HOOK_SRC' ma core.hooksPath = '$ACTIVE'." >&2
-      echo "    Esegui per riattivarli:  git config core.hooksPath $HOOK_SRC" >&2
+      echo "⚠️  WARNING: git hooks INACTIVE — the versioned hooks live in '$HOOK_SRC' but core.hooksPath = '$ACTIVE'." >&2
+      echo "    Re-activate them with:  git config core.hooksPath $HOOK_SRC" >&2
       ;;
   esac
 fi
@@ -451,11 +500,11 @@ npm run build
 ```
 
 If build fails → STOP and report. Do NOT continue — the worktree is broken.
-If only tsc/lint fails → report but continue (develop should be clean, may be a transient issue).
+If only tsc/lint fails → report but continue (the trunk branch should be clean, may be a transient issue).
 
 ### 6. Update registry
 
-Add entry to `.worktrees/registry.json` with all fields: card, cards, groupParent, slug, branch, absolute path, port, `createdAt`, `envSyncedAt`, and `buildVerified`.
+Add entry to `.worktrees/registry.json` with all fields: card, cards, groupParent, slug, branch, `trunkBranch` (the resolved `$TRUNK`), `mainRoot` (the resolved `$MAIN`), absolute path, port, `createdAt`, `envSyncedAt`, and `buildVerified`. Persisting `trunkBranch` + `mainRoot` (R6) lets `/mw`/`/cw` read them back with a presence guard instead of re-deriving or assuming `develop`.
 
 ### 7. Auto-start dev server (if `--dev` flag or `/nw --dev`)
 
@@ -503,8 +552,18 @@ Read `.worktrees/registry.json`. If multiple entries exist or user didn't specif
 
 Fallback: `git worktree list` if registry is missing.
 
-Determine:
+Determine, reading them from the worktree's registry entry (R6):
 - `WORKTREE_PATH`, `BRANCH`, `CARD` (or `CARDS` for batch worktrees)
+- `TRUNK` (the entry's `trunkBranch`) and `MAIN` (the entry's `mainRoot`)
+
+These were persisted at `/nw` time. Before any step below, presence-guard them — if `WORKTREE_PATH`, `TRUNK`, or `MAIN` is empty, HALT with a clear message (never assume `develop` or re-derive `$MAIN` silently):
+
+```bash
+if [ -z "$WORKTREE_PATH" ] || [ -z "$BRANCH" ] || [ -z "$TRUNK" ] || [ -z "$MAIN" ]; then
+  echo "ERROR: missing WORKTREE_PATH/BRANCH/TRUNK/MAIN — read them from the registry entry (fields path/branch/trunkBranch/mainRoot)." >&2
+  exit 1
+fi
+```
 
 ### 2. Env sync check
 
@@ -544,7 +603,7 @@ if [ -n "$CHANGED" ] || [ -n "$UNTRACKED" ]; then
 
 Files were uncommitted when /mw started. This safety commit
 prevents file loss during rebase. Squash-merge will fold this
-into the final commit on develop.
+into the final commit on the trunk branch.
 
 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
 
@@ -552,8 +611,8 @@ Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>"
 fi
 
 # 2. Run quality checks
-# Lint only changed files (vs develop)
-npx eslint --max-warnings=0 $(git diff --name-only develop -- '*.ts' '*.tsx')
+# Lint only changed files (vs the trunk branch)
+npx eslint --max-warnings=0 $(git diff --name-only "origin/$TRUNK" -- '*.ts' '*.tsx')
 npx tsc --noEmit
 
 # Full build (required before PR per AGENTS.md)
@@ -586,48 +645,51 @@ git commit -m "[<CARD-ID>] <description>"
 
 **Programmatic mode**: The orchestrator handles per-card commits in Phase 4. `/mw` only needs to rebase and push (see steps 4b and 4c below).
 
-### 4b. Rebase onto latest develop (MUST — prevents PR merge conflicts)
+### 4b. Rebase onto latest trunk (MUST — prevents PR merge conflicts)
 
-Before pushing, ALWAYS rebase the feature branch onto the latest develop to avoid merge conflicts at PR merge time.
+Before pushing, ALWAYS rebase the feature branch onto the latest trunk branch to avoid merge conflicts at PR merge time. The trunk branch is `git.trunk_branch` from `baldart.config.yml` (resolved below).
 
 ```bash
+# Presence guard (R6): $MAIN and $WORKTREE_PATH MUST already be set + non-empty
+# (written to the registry at /nw time; re-read from there if absent). Never
+# proceed with an undefined $MAIN — it would resolve git operations against the
+# wrong repo.
+if [ -z "$MAIN" ] || [ -z "$WORKTREE_PATH" ]; then
+  echo "ERROR: \$MAIN and/or \$WORKTREE_PATH unset — read them from .worktrees/registry.json before step 4b." >&2
+  exit 1
+fi
+
+# Resolve the trunk branch from config (default: read by the caller; no bare
+# 'develop' literal). TRUNK MUST be non-empty.
+if [ -z "$TRUNK" ]; then
+  echo "ERROR: \$TRUNK (git.trunk_branch) unset — resolve it from baldart.config.yml before step 4b." >&2
+  exit 1
+fi
+
 cd "$WORKTREE_PATH"
 
-# 1. Check for uncommitted changes BEFORE stashing
-#    If the safety commit in step 3 ran, this should be clean.
-#    But if called outside /mw flow, there might be leftovers.
+# 1. NO `git stash` in a worktree (refs/stash is shared across all worktrees via
+#    git.commondir — see FEAT-0522 incident + Safety Rules). The safety commit in
+#    step 3 already guarantees a clean working tree. If the tree is unexpectedly
+#    dirty here (someone wrote between step 3 and step 4b), STOP and report — the
+#    right recovery is a SECOND safety commit, never a stash.
 DIRTY=$(git status --porcelain 2>/dev/null)
-STASHED="false"
 if [ -n "$DIRTY" ]; then
-  echo "⚠️ Dirty working tree before rebase — stashing"
-  STASH_MSG="pre-rebase-$(date +%s)"
-  git stash push --include-untracked -m "$STASH_MSG"
-  STASHED="true"
+  echo "ERROR: working tree dirty in $WORKTREE_PATH after the step-3 safety commit." >&2
+  echo "Files: $DIRTY" >&2
+  echo "Make a second safety commit (explicit file names) — NEVER stash (refs/stash shared across worktrees)." >&2
+  exit 1
 fi
 
-# 2. Fetch latest develop
-git fetch origin develop
+# 2. Fetch latest trunk
+git fetch origin "$TRUNK"
 
-# 3. Rebase onto origin/develop
-git rebase origin/develop 2>&1
+# 3. Rebase onto origin/<trunk>
+git rebase "origin/$TRUNK" 2>&1
 REBASE_EXIT=$?
 ```
 
-**If rebase succeeds** (exit 0): restore stash and continue to push.
-
-```bash
-if [ "$STASHED" = "true" ]; then
-  STASH_NUM=$(git stash list | grep "$STASH_MSG" | sed -E 's/stash@\{([0-9]+)\}.*/\1/')
-  if [ -n "$STASH_NUM" ]; then
-    if ! git stash pop "stash@{$STASH_NUM}" 2>&1; then
-      echo "⚠️ STASH POP FAILED — files preserved in stash@{$STASH_NUM} ($STASH_MSG)"
-      echo "Run 'git stash show stash@{$STASH_NUM}' to see affected files"
-      echo "Run 'git stash pop stash@{$STASH_NUM}' to recover manually"
-      # DO NOT silently continue — report this to the user
-    fi
-  fi
-fi
-```
+**If rebase succeeds** (exit 0): continue straight to push — there is no stash to restore.
 
 **If rebase fails with conflicts**: apply the auto-resolution protocol below.
 
@@ -645,8 +707,8 @@ internal structure (tables, key/value blocks, code).
 | Category | Patterns | Action | Note |
 |----------|----------|--------|------|
 | **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 `docs/metrics/`** | `docs/metrics/*.jsonl`, `docs/metrics/**/*.jsonl` | Auto-resolve: strip markers, keep both sides | JSONL is line-oriented and additive — duplicating both branches' lines yields a valid file. |
-| **Other `.jsonl`** | `*.jsonl` outside `docs/metrics/` | STOP — abort and report | Fixtures, seeds, training data: auto-strip can corrupt them. The user must inspect. |
+| **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. |
 | **Code** | `src/**/*.ts`, `*.tsx`, `*.js`, `*.jsx` | STOP — abort rebase, report to user | |
 | **Tests** | `*.test.*`, `*.spec.*` | Manual only — report to user | |
@@ -681,10 +743,8 @@ for FILE in $CONFLICTED; do
   case "$FILE" in
     src/*.ts|src/*.tsx|src/*.js|src/*.jsx|*.test.*|*.spec.*)
       git rebase --abort
-      # When invoked from /mw (code worktree) a stash may have been created
-      # at the start of step 4b. Pop it back. mw-docs never stashes
-      # (safety commit step 1 leaves the tree clean) so the pop is a no-op.
-      git stash pop 2>/dev/null || true
+      # No stash to restore: step 3's safety commit leaves the tree clean, and
+      # step 4b NEVER stashes (refs/stash is shared across worktrees).
       echo "CONFLICT in $FILE — cannot auto-resolve" >&2
       exit 1 ;;
   esac
@@ -696,7 +756,6 @@ for FILE in $CONFLICTED; do
       if ! validate_structured_md "$FILE"; then
         git checkout --conflict=merge "$FILE" 2>/dev/null || true
         git rebase --abort
-        git stash pop 2>/dev/null || true
         echo "CONFLICT in structured registry $FILE produced invalid structure after auto-strip — manual resolution required." >&2
         exit 1
       fi
@@ -707,21 +766,19 @@ for FILE in $CONFLICTED; do
     field-registry.*)
       # field-registry.json typically — strict JSON, can't auto-strip safely
       git rebase --abort
-      git stash pop 2>/dev/null || true
       echo "CONFLICT in structured registry $FILE — JSON cannot be auto-stripped." >&2
       exit 1 ;;
   esac
 
-  # 3. JSONL — only auto-resolve under docs/metrics/
+  # 3. JSONL — only auto-resolve under ${paths.metrics}/
   case "$FILE" in
-    docs/metrics/*.jsonl|docs/metrics/**/*.jsonl)
+    ${paths.metrics}/*.jsonl|${paths.metrics}/**/*.jsonl)
       sed -i '' '/^<<<<<<< /d; /^=======/d; /^>>>>>>> /d' "$FILE"
       git add "$FILE"
       continue ;;
     *.jsonl)
       git rebase --abort
-      git stash pop 2>/dev/null || true
-      echo "CONFLICT in $FILE (.jsonl outside docs/metrics/ — may be fixture/seed) — manual resolution required." >&2
+      echo "CONFLICT in $FILE (.jsonl outside ${paths.metrics}/ — may be fixture/seed) — manual resolution required." >&2
       exit 1 ;;
   esac
 
@@ -733,26 +790,30 @@ for FILE in $CONFLICTED; do
   esac
 done
 
-# Continue rebase + restore stash + verify build
+# Continue rebase + verify build (no stash to restore — step 4b never stashes)
 git rebase --continue
-git stash pop 2>/dev/null || true
 npm run build
 ```
 
 If build fails after rebase → STOP and report. The rebase introduced incompatibilities.
 
-### 4c. Land the feature branch onto develop (strategy-branched)
+### 4c. Land the feature branch onto the trunk branch (strategy-branched)
 
-**IMPORTANT — NO local checkout/switch/branch on the main repo, regardless of strategy.** Consumer projects share the main repo as a parallel resource across multiple terminals; running `git checkout develop` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. Both strategies below operate from the worktree and the main repo's `HEAD` is never touched.
+**IMPORTANT — NO local checkout/switch/branch on the main repo, regardless of strategy.** Consumer projects share the main repo as a parallel resource across multiple terminals; running `git checkout <trunk>` on it preempts whatever the other terminals are doing and breaks worktree-driven workflows. Both strategies below operate from the worktree and the main repo's `HEAD` is never touched.
 
 Read `git.merge_strategy` from `baldart.config.yml` (default: `pr`):
 
 ```bash
-MAIN=$(git -C "$WORKTREE_PATH" rev-parse --git-common-dir)/..
-MAIN=$(cd "$MAIN" && pwd)
+# $MAIN and $TRUNK were resolved in step 1 (read from the registry entry, R6) and
+# presence-guarded. Fall back to deriving $MAIN from git-common-dir ONLY if it is
+# still unset — never silently re-derive over a value the registry already supplied.
+if [ -z "$MAIN" ]; then
+  MAIN=$(git -C "$WORKTREE_PATH" rev-parse --git-common-dir)/..
+  MAIN=$(cd "$MAIN" && pwd)
+fi
 
 # Resolve strategy from baldart.config.yml (default: pr)
-STRATEGY=$(grep -A1 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
+STRATEGY=$(grep -A40 '^git:' "$MAIN/baldart.config.yml" 2>/dev/null \
   | grep 'merge_strategy:' | head -1 \
   | sed -E 's/.*merge_strategy:[[:space:]]*([a-z-]+).*/\1/' || echo "pr")
 STRATEGY=${STRATEGY:-pr}
@@ -764,7 +825,7 @@ If neither `pr` nor `local-push` resolves, ASK the user once which to use and su
 
 #### Strategy A — `pr` (default, GitHub PR via `gh`)
 
-Use this when `develop` is protected on origin (required status checks, reviews, merge queue) — a direct push would be rejected.
+Use this when the trunk branch is protected on origin (required status checks, reviews, merge queue) — a direct push would be rejected.
 
 ```bash
 # 1. Push the feature branch to origin (force-with-lease in case of rebase in 4b).
@@ -776,7 +837,7 @@ PR_NUMBER=$(gh -R "$(gh repo view --json nameWithOwner -q .nameWithOwner)" pr li
 
 if [ -z "$PR_NUMBER" ]; then
   PR_URL=$(gh pr create \
-    --base develop \
+    --base "$TRUNK" \
     --head "$BRANCH" \
     --title "[<CARD-ID>] $(echo "$BRANCH" | sed 's|.*/||')" \
     --body "Auto-merged by /mw after final review + QA passed." \
@@ -797,7 +858,7 @@ if [ "$PR_STATE" != "MERGED" ]; then
   REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
   gh api -X PUT "repos/$REPO/pulls/$PR_NUMBER/merge" \
     -f merge_method=merge \
-    -f commit_title="[<CARD-ID>] Merge $BRANCH into develop"
+    -f commit_title="[<CARD-ID>] Merge $BRANCH into $TRUNK"
   PR_STATE=$(gh pr view "$PR_NUMBER" --json state -q .state)
 fi
 
@@ -805,47 +866,47 @@ if [ "$PR_STATE" != "MERGED" ]; then
   echo "❌ PR #$PR_NUMBER did not merge. Inspect manually: $PR_URL"
   exit 1
 fi
-echo "✅ PR #$PR_NUMBER merged to develop."
+echo "✅ PR #$PR_NUMBER merged to $TRUNK."
 ```
 
 If `gh` is not installed in the project, STOP and ask the user to install GitHub CLI (`brew install gh` or equivalent) and run `gh auth login`. Do NOT fall back to a local checkout — it violates terminal isolation.
 
-If both gh CLI and REST API merge fail → STOP and report. Suggest switching to `merge_strategy: local-push` only if `develop` is NOT protected on origin.
+If both gh CLI and REST API merge fail → STOP and report. Suggest switching to `merge_strategy: local-push` only if the trunk branch is NOT protected on origin.
 
 ---
 
 #### Strategy B — `local-push` (direct FF push, no PR)
 
-Use this when `develop` is NOT protected on origin and the user wants to skip the GitHub PR roundtrip. After step 4b the feature branch is rebased onto `origin/develop`, so it can fast-forward `develop` on origin in a single push.
+Use this when the trunk branch is NOT protected on origin and the user wants to skip the GitHub PR roundtrip. After step 4b the feature branch is rebased onto `origin/$TRUNK`, so it can fast-forward the trunk on origin in a single push.
 
 ```bash
-# 1. Sanity: confirm the feature branch is strictly ahead of origin/develop
-#    (i.e. the rebase in step 4b succeeded and we can FF develop on origin).
-git -C "$WORKTREE_PATH" fetch origin develop --quiet
-AHEAD=$(git -C "$WORKTREE_PATH" rev-list --count "origin/develop..$BRANCH")
-BEHIND=$(git -C "$WORKTREE_PATH" rev-list --count "$BRANCH..origin/develop")
+# 1. Sanity: confirm the feature branch is strictly ahead of origin/$TRUNK
+#    (i.e. the rebase in step 4b succeeded and we can FF the trunk on origin).
+git -C "$WORKTREE_PATH" fetch origin "$TRUNK" --quiet
+AHEAD=$(git -C "$WORKTREE_PATH" rev-list --count "origin/$TRUNK..$BRANCH")
+BEHIND=$(git -C "$WORKTREE_PATH" rev-list --count "$BRANCH..origin/$TRUNK")
 if [ "$BEHIND" -ne 0 ]; then
-  echo "❌ local-push aborted: $BRANCH is $BEHIND commit(s) behind origin/develop." >&2
-  echo "   Re-run step 4b (rebase onto origin/develop), then retry." >&2
+  echo "❌ local-push aborted: $BRANCH is $BEHIND commit(s) behind origin/$TRUNK." >&2
+  echo "   Re-run step 4b (rebase onto origin/$TRUNK), then retry." >&2
   exit 1
 fi
 if [ "$AHEAD" -eq 0 ]; then
-  echo "ℹ️ Nothing to push — $BRANCH is identical to origin/develop. Skipping."
+  echo "ℹ️ Nothing to push — $BRANCH is identical to origin/$TRUNK. Skipping."
 else
-  echo "Fast-forwarding origin/develop by $AHEAD commit(s) via local-push…"
+  echo "Fast-forwarding origin/$TRUNK by $AHEAD commit(s) via local-push…"
 fi
 
-# 2. Direct fast-forward push to develop on origin. No PR.
-#    If develop is protected on origin, this fails — surface the hint and stop.
-if ! PUSH_OUTPUT=$(git -C "$WORKTREE_PATH" push origin "$BRANCH:develop" 2>&1); then
+# 2. Direct fast-forward push to the trunk on origin. No PR.
+#    If the trunk is protected on origin, this fails — surface the hint and stop.
+if ! PUSH_OUTPUT=$(git -C "$WORKTREE_PATH" push origin "$BRANCH:$TRUNK" 2>&1); then
   echo "$PUSH_OUTPUT"
   if echo "$PUSH_OUTPUT" | grep -qiE "protected branch|required status|review required"; then
-    echo "❌ local-push rejected: 'develop' is protected on origin." >&2
+    echo "❌ local-push rejected: '$TRUNK' is protected on origin." >&2
     echo "   Switch baldart.config.yml → git.merge_strategy: pr, or remove the protection." >&2
   fi
   exit 1
 fi
-echo "✅ $BRANCH merged into develop on origin (fast-forward, no PR)."
+echo "✅ $BRANCH merged into $TRUNK on origin (fast-forward, no PR)."
 
 # 3. Delete the remote feature branch (best-effort — never fatal).
 git -C "$WORKTREE_PATH" push origin --delete "$BRANCH" 2>/dev/null || true
@@ -856,60 +917,62 @@ PR_NUMBER=""
 
 ---
 
-#### Common — sync local develop ref (both strategies)
+#### Common — sync local trunk ref (both strategies)
 
 ```bash
-# Sync local develop ONLY if the main repo's HEAD is already develop.
-# NEVER `git checkout develop` here. If the user (or another terminal) had
-# develop checked out, ff-only updates it cleanly. Otherwise we leave their
-# HEAD alone and they'll pull next time.
+# Sync the local trunk ($TRUNK) ONLY if the main repo's HEAD is already on it.
+# NEVER `git checkout "$TRUNK"` here. If the user (or another terminal) had the
+# trunk checked out, ff-only updates it cleanly. Otherwise we leave their HEAD
+# alone and they'll pull next time. $TRUNK and $MAIN were resolved + presence-
+# guarded in step 1 (read from the registry, R6).
 CURRENT_BRANCH=$(git -C "$MAIN" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
-if [ "$CURRENT_BRANCH" = "develop" ]; then
-  if git -C "$MAIN" pull --ff-only origin develop 2>/dev/null; then
-    echo "✅ Main repo develop fast-forwarded to origin/develop."
+if [ "$CURRENT_BRANCH" = "$TRUNK" ]; then
+  if git -C "$MAIN" pull --ff-only origin "$TRUNK" 2>/dev/null; then
+    echo "✅ Main repo $TRUNK fast-forwarded to origin/$TRUNK."
   else
     # FF blocked. NEVER leave this as a passive "Leaving as-is" TODO for the user
     # (v3.39.0 — the finalizer MUST conclude). The cause is almost always an
     # uncommitted append to the framework-owned telemetry log left by a prior run.
     # Partition the dirty tree:
-    #   - framework-owned artifact (docs/metrics/skill-runs.jsonl) → auto-reconcile
+    #   - framework-owned artifact (${paths.metrics}/skill-runs.jsonl) → auto-reconcile
     #     (commit + rebase) so the ff completes with zero data loss;
     #   - ANY foreign file → emit a decision marker the orchestrator MUST convert
     #     into ONE explicit user gate. Never auto-commit work this run did not own.
+    METRICS_LOG="${paths.metrics}/skill-runs.jsonl"   # paths.metrics default: docs/metrics
     DIRTY=$(git -C "$MAIN" status --porcelain --untracked-files=no | sed 's/^...//')
     FOREIGN=""
     OWNED=""
     for f in $DIRTY; do
       case "$f" in
-        docs/metrics/skill-runs.jsonl) OWNED="$OWNED $f" ;;
+        "$METRICS_LOG") OWNED="$OWNED $f" ;;
         *) FOREIGN="$FOREIGN $f" ;;
       esac
     done
     if [ -n "$FOREIGN" ]; then
-      echo "[SYNC-NEEDS-DECISION] main repo develop cannot fast-forward; foreign uncommitted files:${FOREIGN} — orchestrator MUST raise ONE explicit user gate (commit / user-handles), never a passive note."
+      echo "[SYNC-NEEDS-DECISION] main repo $TRUNK cannot fast-forward; foreign uncommitted files:${FOREIGN} — orchestrator MUST raise ONE explicit user gate (commit / user-handles), never a passive note."
     elif [ -n "$OWNED" ]; then
       # Only framework-owned telemetry is dirty → reconcile autonomously, lossless.
-      git -C "$MAIN" add docs/metrics/skill-runs.jsonl
-      git -C "$MAIN" commit -m "chore(metrics): reconcile skill-runs telemetry before develop sync" --quiet
-      if git -C "$MAIN" pull --rebase origin develop 2>/dev/null; then
-        git -C "$MAIN" push origin develop 2>/dev/null \
-          && echo "✅ Reconciled stale metrics log + synced develop to origin." \
-          || echo "✅ Reconciled stale metrics log (local develop 1 commit ahead; syncs on next push). Tree clean."
+      git -C "$MAIN" add "$METRICS_LOG"
+      git -C "$MAIN" commit -m "chore(metrics): reconcile skill-runs telemetry before $TRUNK sync" --quiet
+      if git -C "$MAIN" pull --rebase origin "$TRUNK" 2>/dev/null; then
+        git -C "$MAIN" push origin "$TRUNK" 2>/dev/null \
+          && echo "✅ Reconciled stale metrics log + synced $TRUNK to origin." \
+          || echo "✅ Reconciled stale metrics log (local $TRUNK 1 commit ahead; syncs on next push). Tree clean."
       else
         git -C "$MAIN" rebase --abort 2>/dev/null || true
-        echo "[SYNC-NEEDS-DECISION] metrics rebase conflict on develop — orchestrator MUST raise ONE explicit user gate."
+        echo "[SYNC-NEEDS-DECISION] metrics rebase conflict on $TRUNK — orchestrator MUST raise ONE explicit user gate."
       fi
     else
-      echo "[SYNC-NEEDS-DECISION] main repo develop cannot fast-forward and the working tree is clean (diverged?) — orchestrator MUST raise ONE explicit user gate."
+      echo "[SYNC-NEEDS-DECISION] main repo $TRUNK cannot fast-forward and the working tree is clean (diverged?) — orchestrator MUST raise ONE explicit user gate."
     fi
   fi
 else
-  echo "ℹ️ Main repo HEAD is '$CURRENT_BRANCH' — not switching. Next manual `git pull` on develop will sync."
-  git -C "$MAIN" fetch origin develop --quiet
+  echo "ℹ️ Main repo HEAD is '$CURRENT_BRANCH' — not switching. Next manual \`git pull\` on $TRUNK will sync."
+  git -C "$MAIN" fetch origin "$TRUNK" --quiet
   # Structured marker for upstream orchestrators (e.g. /new Phase 6c).
   # `/mw` standalone keeps fetch-only behavior (terminal isolation); orchestrators
   # parse this marker and route reconciliation through an explicit user gate.
-  echo "[SYNC-DEFERRED] main repo HEAD=${CURRENT_BRANCH}, local develop not fast-forwarded — orchestrator workspace-hygiene phase must reconcile."
+  echo "[SYNC-DEFERRED] main repo HEAD=${CURRENT_BRANCH}, local $TRUNK not fast-forwarded — orchestrator workspace-hygiene phase must reconcile."
 fi
 ```
 
@@ -941,10 +1004,10 @@ git branch -d "$BRANCH"
 ```
 
 ```bash
-# 3. Delete the remote branch. The branch is ALREADY MERGED into develop at this
+# 3. Delete the remote branch. The branch is ALREADY MERGED into the trunk at this
 #    point, so this is routine cleanup — NOT the gated "branch deletion" that needs
 #    owner approval (see AGENTS.md § branch deletion). Report the outcome; never
-#    degrade a failure into a passive "puoi cancellarlo a mano" note handed to the user.
+#    degrade a failure into a passive "you can delete it by hand" note handed to the user.
 if git push origin --delete "$BRANCH" 2>/dev/null; then
   echo "✅ Remote branch '$BRANCH' deleted (merged → routine cleanup)."
 else
@@ -971,9 +1034,9 @@ Merge complete:
   Branch:   <BRANCH> (deleted on remote — merged branch deletion is routine cleanup, never gated)
   Strategy: <pr | local-push>
   PR:       #<PR_NUMBER> merged via `gh pr merge`    ← only in `pr` strategy
-  Push:     fast-forward to origin/develop           ← only in `local-push` strategy
+  Push:     fast-forward to origin/<trunk>           ← only in `local-push` strategy
   Worktree: <WORKTREE_PATH> (removed)
-  develop:  remote up to date; local main-repo synced (auto-reconciled framework
+  <trunk>:  remote up to date; local main-repo synced (auto-reconciled framework
             telemetry if it blocked the ff). Any [SYNC-NEEDS-DECISION] /
             [SYNC-DEFERRED] marker above is for the orchestrator to gate on —
             NOT a residue to hand the user as a manual TODO.
@@ -1010,7 +1073,7 @@ Active worktrees:
 ```
 
 **Stale detection**: Worktrees older than 7 days get a warning.
-**Merged detection**: If the branch has been merged into develop (`git branch -a --merged develop`), flag as "already merged — safe to /cw".
+**Merged detection**: If the branch has been merged into the trunk branch — read each entry's `trunkBranch`, e.g. `git branch -a --merged "$TRUNK"` — flag as "already merged — safe to /cw".
 **Orphan detection**: Worktrees in `git worktree list` but NOT in registry get flagged as "unregistered".
 
 ---
@@ -1028,8 +1091,8 @@ Remove worktrees without the full PR/merge flow. Use for:
 git worktree list
 ```
 
-Cross-reference with registry. For each worktree, check:
-- Is the branch merged into develop? → "safe to remove"
+Cross-reference with registry. For each worktree, check (using its `trunkBranch`):
+- Is the branch merged into the trunk branch? → "safe to remove"
 - Is the branch pushed to remote? → "has remote backup"
 - Are there uncommitted changes? → "has uncommitted work — DANGEROUS"
 
@@ -1038,7 +1101,7 @@ Cross-reference with registry. For each worktree, check:
 ```
 Worktrees available for cleanup:
 
-  1. feat/FEAT-0200-menu-ranking — merged into develop ✓ safe
+  1. feat/FEAT-0200-menu-ranking — merged into trunk ✓ safe
   2. feat/BUG-0300-old-fix — not merged, pushed to remote
   3. feat/FEAT-0100-abandoned — not merged, uncommitted changes ✗ DANGEROUS
 
@@ -1085,16 +1148,16 @@ Cleanup complete:
 
 ## Safety Rules
 
-- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use the configured `git.merge_strategy` for develop merges and `git -C <main> pull --ff-only` (only when `HEAD = develop` already) for sync. See `/mw` step 4c.
-- NEVER merge to `main` — only to `develop`, via the configured `git.merge_strategy` (`pr` → `gh pr merge`; `local-push` → `git push origin <feat>:develop`). NEVER via local checkout.
+- **NEVER `git checkout`, `git switch`, `git checkout -b`, or `git branch` on the main repo from inside `/mw` / `/nw` / `/cw`.** The main repo is a shared resource across parallel terminals; touching its `HEAD` preempts other agents and breaks worktree-driven workflows. Many consumer projects declare this as an absolute rule in CLAUDE.md and Claude Code's classifier will pattern-match and block these commands preemptively. Use the configured `git.merge_strategy` for trunk-branch merges and `git -C <main> pull --ff-only` (only when `HEAD = git.trunk_branch` already) for sync. See `/mw` step 4c.
+- NEVER merge to a production/release branch — only to the configured trunk branch (`git.trunk_branch`), via the configured `git.merge_strategy` (`pr` → `gh pr merge`; `local-push` → `git push origin <feat>:<git.trunk_branch>`). NEVER via local checkout.
 - NEVER force push from a worktree (`--force-with-lease` on the feature branch after rebase is the only allowed force variant).
 - NEVER `git add .` or `git add -A` — always explicit file names.
 - NEVER remove a worktree with uncommitted changes without explicit user confirmation.
 - NEVER delete a branch before successful merge verification.
-- NEVER cleanup a worktree before confirming develop is stable post-merge.
+- NEVER cleanup a worktree before confirming the trunk branch is stable post-merge.
 - If build/lint/tsc fails during /mw, STOP and report. Do not skip checks.
 - If merge conflicts during /mw, STOP and ask the user. Do not auto-resolve.
-- Always verify `.worktrees/` is in `.gitignore` before creating (already done in this project).
+- 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.
 - **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.