baldart 4.52.4 → 4.53.1

package/framework/.claude/skills/worktree-manager/scripts/setup-worktree.sh

@@ -0,0 +1,457 @@
+#!/usr/bin/env bash
+#
+# setup-worktree.sh — SSOT deterministic CODE-worktree creation + baseline.
+#
+# This is the single source of truth for the worktree build sequence consumed by
+# three callers (no per-caller duplication — the sin CLAUDE.md forbids):
+#   • /nw  (worktree-manager § "/nw") — interactive + slug-only + programmatic
+#   • /new (skill: framework/.claude/skills/new/references/setup.md step 4)
+#   • new2 (framework/.claude/workflows/new2.js Pre-flight)
+#
+# Why a deterministic script instead of a model-driven subagent: the worktree
+# setup is PURE PLUMBING (git worktree add → npm install → env copy → port →
+# registry → baseline). Driving it through a Skill-interpreting subagent put a
+# model in the loop for mechanical work — and the model either FABRICATED a
+# well-formed "baseline: pass" block with nothing on disk (haiku, 2/2), or went
+# IDLE mid-execution leaving a half-built worktree (sonnet, node_modules missing).
+# A deterministic script cannot fabricate or stall: it does the work or fails
+# honestly with a log. Callers launch it as a BACKGROUND Bash, end the turn, and
+# on resume read the structured manifest + run their own disk-verification gate.
+#
+# SCOPE: the FRESH-path only. The caller's git-authoritative idempotency pre-check
+# (setup.md step 4a2) decides resume / reset / fresh BEFORE invoking this — this
+# script assumes a clean slate and fails loud on a branch/path collision (a code
+# worktree is not silently re-creatable). It does NOT repair a failing baseline
+# (role boundary — the coder specialist does that downstream); it reports the
+# failure with a log precise enough to act on.
+#
+# Usage:
+#   setup-worktree.sh --branch <branch> --slug <slug> --manifest <path> [opts]
+#
+# Required:
+#   --branch <branch>      resolved branch name (caller derives it; e.g.
+#                          feat/FEAT-0200-menu-ranking or feat/<slug>)
+#   --slug <slug>          kebab-case slug (used for the log filename only;
+#                          the worktree path derives from --branch)
+#   --manifest <path>      file to write the structured result block to (the
+#                          caller reads THIS at resume — never the bg stdout)
+#
+# Optional (each falls back to baldart.config.yml / autodetect when omitted, so
+# /nw can call with just the three required flags; /new + new2 pass the values
+# they already resolved in Phase 0 to avoid re-deriving / drift):
+#   --card <id>            primary card id            (default: none → null)
+#   --cards <a,b,c>        all card ids sharing the wt (default: [])
+#   --group-parent <id>    group.parent               (default: none → null)
+#   --main <path>          main repo root             (default: resolve_main)
+#   --trunk <branch>       git.trunk_branch           (default: config/autodetect)
+#   --env-files <a,b>      stack.env_files CSV         (default: config / .env.local,.env)
+#   --backlog-dir <dir>    paths.backlog_dir          (default: config / backlog)
+#   --tc-typecheck <cmd>   toolchain typecheck cmd     (default: config / npx tsc --noEmit)
+#   --tc-lint <cmd>        toolchain lint cmd          (default: config / npx eslint --max-warnings=0 src/)
+#   --tc-build <cmd>       toolchain build cmd         (default: config / npm run build)
+#   --install-cmd <cmd>    dependency install cmd      (default: npm install)
+#   --log <path>           install/build log sink      (default: /tmp/wt-setup-<slug>.log)
+#   --port-min <n>         port scan floor            (default: 3001)
+#   --port-max <n>         port scan ceiling          (default: 3099)
+#   --build-timeout <s>    hard build timeout seconds  (default: 600)
+#
+# Manifest written (parsed by callers — STABLE contract):
+#   status: ok | error
+#   error: <message | ->
+#   worktree_path: <abs | ->
+#   branch: <branch>
+#   port: <n | ->
+#   created_at: <ISO-8601 | ->     (stamped at worktree creation, NOT at finish)
+#   baseline: pass | fail | timeout | -
+#   baseline_log: <path | ->
+#
+# Exit: 0 on a VERIFIED worktree with baseline:pass; non-zero otherwise. The
+# caller never trusts the exit code or the manifest as the sole evidence — it
+# re-verifies the worktree on disk (setup.md step 6a). This script writes the
+# manifest on EVERY exit path so a non-zero exit is always diagnosable.
+
+set -u
+
+err() { printf '%s\n' "$*" >&2; }
+
+# --- args ------------------------------------------------------------------
+BRANCH= SLUG= MANIFEST= CARD= CARDS= GROUP_PARENT= MAIN= TRUNK=
+ENV_FILES_ARG= BACKLOG_DIR= TC_TC= TC_LINT= TC_BUILD= INSTALL_CMD=
+LOG= PORT_MIN=3001 PORT_MAX=3099 BUILD_TIMEOUT=600
+ENV_FILES_SET=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --branch) BRANCH="${2:-}"; shift 2 ;;
+    --slug) SLUG="${2:-}"; shift 2 ;;
+    --manifest) MANIFEST="${2:-}"; shift 2 ;;
+    --card) CARD="${2:-}"; shift 2 ;;
+    --cards) CARDS="${2:-}"; shift 2 ;;
+    --group-parent) GROUP_PARENT="${2:-}"; shift 2 ;;
+    --main) MAIN="${2:-}"; shift 2 ;;
+    --trunk) TRUNK="${2:-}"; shift 2 ;;
+    --env-files) ENV_FILES_ARG="${2:-}"; ENV_FILES_SET=1; shift 2 ;;
+    --backlog-dir) BACKLOG_DIR="${2:-}"; shift 2 ;;
+    --tc-typecheck) TC_TC="${2:-}"; shift 2 ;;
+    --tc-lint) TC_LINT="${2:-}"; shift 2 ;;
+    --tc-build) TC_BUILD="${2:-}"; shift 2 ;;
+    --install-cmd) INSTALL_CMD="${2:-}"; shift 2 ;;
+    --log) LOG="${2:-}"; shift 2 ;;
+    --port-min) PORT_MIN="${2:-}"; shift 2 ;;
+    --port-max) PORT_MAX="${2:-}"; shift 2 ;;
+    --build-timeout) BUILD_TIMEOUT="${2:-}"; shift 2 ;;
+    *) err "ERROR: unknown arg: $1"; exit 2 ;;
+  esac
+done
+
+# --- manifest writer (called on EVERY exit path) ---------------------------
+M_STATUS="error" M_ERROR="-" M_WTPATH="-" M_PORT="-" M_CREATED="-" M_BASELINE="-" M_BLOG="-"
+write_manifest() {
+  [ -n "$MANIFEST" ] || return 0
+  {
+    printf 'status: %s\n' "$M_STATUS"
+    printf 'error: %s\n' "$M_ERROR"
+    printf 'worktree_path: %s\n' "$M_WTPATH"
+    printf 'branch: %s\n' "${BRANCH:--}"
+    printf 'port: %s\n' "$M_PORT"
+    printf 'created_at: %s\n' "$M_CREATED"
+    printf 'baseline: %s\n' "$M_BASELINE"
+    printf 'baseline_log: %s\n' "$M_BLOG"
+  } > "$MANIFEST" 2>/dev/null || true
+}
+fail() { M_STATUS="error"; M_ERROR="$1"; write_manifest; err "ERROR: $1"; exit "${2:-1}"; }
+
+[ -n "$BRANCH" ]   || { err "ERROR: --branch is required"; exit 2; }
+[ -n "$SLUG" ]     || { err "ERROR: --slug is required"; exit 2; }
+[ -n "$MANIFEST" ] || { err "ERROR: --manifest is required"; exit 2; }
+
+# --- canonical main-repo-root resolver (mirrors allocate-id.sh resolve_main;
+#     inlined by the same rationale that script documents — it is not on disk
+#     inside a freshly-checked-out worktree, and sourcing across the freshly
+#     created worktree boundary is fragile). Built on --show-toplevel, NEVER
+#     --git-common-dir+parent (wrong under git init --separate-git-dir). -------
+resolve_main() {
+  local top gd common
+  top="$(git rev-parse --show-toplevel 2>/dev/null)" || return 1
+  gd="$(git rev-parse --git-dir 2>/dev/null)" || return 1
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  if [ "$gd" = "$common" ]; then
+    printf '%s\n' "$top"
+  else
+    (cd "$top/.." 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null) || return 1
+  fi
+}
+
+# --- read a paths.* / git.* / stack.* scalar from baldart.config.yml --------
+config_scalar() {
+  local block="$1" key="$2" cfg="$MAIN/baldart.config.yml"
+  [ -f "$cfg" ] || return 0
+  grep -A60 "^${block}:" "$cfg" 2>/dev/null \
+    | grep -m1 "[[:space:]]*${key}:" \
+    | sed -E "s/.*${key}:[[:space:]]*\"?([^\"#]*)\"?.*/\1/" \
+    | sed -E 's/[[:space:]]+$//'
+}
+
+# --- resolve MAIN ----------------------------------------------------------
+if [ -z "$MAIN" ]; then
+  MAIN="$(resolve_main)" || fail "cannot resolve main repo root (not inside a git repository)" 1
+fi
+[ -d "$MAIN/.git" ] || [ -e "$MAIN/.git" ] || fail "resolved main '$MAIN' is not a git repo" 1
+
+# --- resolve TRUNK (config → origin/HEAD → develop/main/master) -------------
+if [ -z "$TRUNK" ]; then
+  TRUNK="$(config_scalar git trunk_branch)"
+fi
+if [ -z "$TRUNK" ]; then
+  TRUNK="$(git -C "$MAIN" symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed -E 's#^refs/remotes/origin/##' || true)"
+fi
+if [ -z "$TRUNK" ]; then
+  for cand in develop main master; do
+    if git -C "$MAIN" show-ref --verify --quiet "refs/heads/$cand"; then TRUNK="$cand"; break; fi
+  done
+fi
+[ -n "$TRUNK" ] || fail "git.trunk_branch unresolved (config + origin/HEAD + develop/main/master all empty)" 1
+
+# --- resolve env_files (CSV → array; default .env.local,.env when unset) ----
+ENV_FILES=()
+if [ "$ENV_FILES_SET" = 1 ]; then
+  # explicit --env-files wins, even if empty (caller may intentionally pass none)
+  IFS=',' read -r -a ENV_FILES <<< "$ENV_FILES_ARG"
+else
+  # not passed → try config stack.env_files (CSV/inline-list best-effort), else default
+  cfg_env="$(grep -A4 '^[[:space:]]*env_files:' "$MAIN/baldart.config.yml" 2>/dev/null | tr -d '[]"' | grep -oE "\.[A-Za-z0-9._/-]+" | tr '\n' ',' || true)"
+  if [ -n "$cfg_env" ]; then
+    IFS=',' read -r -a ENV_FILES <<< "$cfg_env"
+  else
+    ENV_FILES=( ".env.local" ".env" )
+  fi
+fi
+# strip whitespace from each entry
+_clean=(); for ef in "${ENV_FILES[@]:-}"; do ef="$(printf '%s' "$ef" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"; [ -n "$ef" ] && _clean+=("$ef"); done
+ENV_FILES=("${_clean[@]:-}")
+
+# --- resolve backlog dir + toolchain commands ------------------------------
+[ -n "$BACKLOG_DIR" ] || { BACKLOG_DIR="$(config_scalar paths backlog_dir)"; [ -n "$BACKLOG_DIR" ] || BACKLOG_DIR="backlog"; }
+[ -n "$INSTALL_CMD" ] || INSTALL_CMD="npm install"
+# toolchain.commands.* only when features.has_toolchain: true; else the defaults.
+_tc() {
+  local cfg="$MAIN/baldart.config.yml"
+  grep -E '^[[:space:]]*has_toolchain:[[:space:]]*true' "$cfg" >/dev/null 2>&1 || return 0
+  grep -A20 '^toolchain:' "$cfg" 2>/dev/null | grep -A15 '^[[:space:]]*commands:' \
+    | grep -E "^[[:space:]]+$1:" | head -1 \
+    | sed -E "s/.*$1:[[:space:]]*\"?([^\"#]*)\"?.*/\1/" | sed -E 's/[[:space:]]+$//'
+}
+[ -n "$TC_TC" ]    || TC_TC="$(_tc typecheck)";   [ -n "$TC_TC" ]    || TC_TC="npx tsc --noEmit"
+[ -n "$TC_LINT" ]  || TC_LINT="$(_tc lint)";      [ -n "$TC_LINT" ]  || TC_LINT="npx eslint --max-warnings=0 src/"
+[ -n "$TC_BUILD" ] || TC_BUILD="$(_tc build)";    [ -n "$TC_BUILD" ] || TC_BUILD="npm run build"
+
+# --- log sink --------------------------------------------------------------
+[ -n "$LOG" ] || LOG="/tmp/wt-setup-${SLUG}.log"
+: > "$LOG" 2>/dev/null || true
+
+# --- worktree path is deterministic from the branch (R8) -------------------
+WT_REL=".worktrees/$(printf '%s' "$BRANCH" | tr '/' '-')"
+WT_ABS="$MAIN/$WT_REL"
+M_WTPATH="$WT_ABS"
+
+# --- lock helpers (mkdir is atomic on POSIX; same pattern as allocate-id.sh) -
+WT_DIR="$MAIN/.worktrees"
+LOCKDIR="$WT_DIR/.wt-setup.lock"
+LOCK_STALE_SECONDS=30
+LOCK_MAX_TRIES=150
+file_mtime() { stat -f %m "$1" 2>/dev/null || stat -c %Y "$1" 2>/dev/null || echo 0; }
+acquire_lock() {
+  local tries=0 now m age
+  mkdir -p "$WT_DIR" 2>/dev/null || true
+  while ! mkdir "$LOCKDIR" 2>/dev/null; do
+    if [ -d "$LOCKDIR" ]; then
+      now="$(date +%s)"; m="$(file_mtime "$LOCKDIR")"
+      case "$m" in ''|*[!0-9]*) m=0 ;; esac
+      age=$(( now - m ))
+      if [ "$m" -gt 0 ] && [ "$age" -gt "$LOCK_STALE_SECONDS" ]; then
+        err "WARN: stealing stale wt-setup lock (age ${age}s)"; rm -rf "$LOCKDIR" 2>/dev/null; continue
+      fi
+    fi
+    tries=$(( tries + 1 ))
+    [ "$tries" -gt "$LOCK_MAX_TRIES" ] && { err "WARN: could not acquire wt-setup lock — proceeding without it (port race possible)"; return 1; }
+    sleep 0.2
+  done
+  printf '%s\n' "$$" > "$LOCKDIR/pid" 2>/dev/null || true
+  return 0
+}
+release_lock() { rm -rf "$LOCKDIR" 2>/dev/null || true; }
+
+# --- registry upsert via node (atomic tmp+rename; no jq dependency) ---------
+# Fields are passed through the environment to avoid bash→JSON quoting hell.
+REG="$WT_DIR/registry.json"
+registry_upsert() {
+  REG_FILE="$REG" \
+  R_CARD="$CARD" R_CARDS="$CARDS" R_GROUP="$GROUP_PARENT" R_SLUG="$SLUG" \
+  R_BRANCH="$BRANCH" R_TRUNK="$TRUNK" R_MAIN="$MAIN" R_PATH="$WT_ABS" \
+  R_PORT="$1" R_CREATED="$M_CREATED" R_ENVSYNCED="$2" R_BUILDVERIFIED="$3" \
+  node -e '
+    const fs = require("fs");
+    const f = process.env.REG_FILE;
+    let reg = { worktrees: [] };
+    try { const j = JSON.parse(fs.readFileSync(f, "utf8")); if (j && Array.isArray(j.worktrees)) reg = j; } catch (_) {}
+    const csv = (s) => (s || "").split(",").map(x => x.trim()).filter(Boolean);
+    const num = (s) => { const n = parseInt(s, 10); return Number.isFinite(n) ? n : null; };
+    const bool = (s) => s === "true" ? true : s === "false" ? false : null;
+    const entry = {
+      card: process.env.R_CARD || null,
+      cards: csv(process.env.R_CARDS),
+      groupParent: process.env.R_GROUP || null,
+      slug: process.env.R_SLUG || null,
+      branch: process.env.R_BRANCH,
+      trunkBranch: process.env.R_TRUNK || null,
+      mainRoot: process.env.R_MAIN || null,
+      path: process.env.R_PATH,
+      port: num(process.env.R_PORT),
+      createdAt: process.env.R_CREATED && process.env.R_CREATED !== "-" ? process.env.R_CREATED : null,
+      envSyncedAt: process.env.R_ENVSYNCED && process.env.R_ENVSYNCED !== "-" ? process.env.R_ENVSYNCED : null,
+      buildVerified: bool(process.env.R_BUILDVERIFIED),
+    };
+    const i = reg.worktrees.findIndex(w => w && w.branch === entry.branch);
+    if (i >= 0) reg.worktrees[i] = { ...reg.worktrees[i], ...entry };
+    else reg.worktrees.push(entry);
+    const tmp = f + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(reg, null, 2) + "\n");
+    fs.renameSync(tmp, f);
+  ' 2>>"$LOG"
+}
+# ports currently held by registry entries (so concurrent setups never collide)
+registry_used_ports() {
+  REG_FILE="$REG" node -e '
+    const fs = require("fs");
+    try {
+      const j = JSON.parse(fs.readFileSync(process.env.REG_FILE, "utf8"));
+      (j.worktrees || []).forEach(w => { if (w && Number.isFinite(w.port)) console.log(w.port); });
+    } catch (_) {}
+  ' 2>/dev/null
+}
+
+# ===========================================================================
+# 1. .gitignore safety (auto-heal, idempotent, non-blocking)
+if [ ! -f "$MAIN/.gitignore" ] || ! grep -qE '^\.worktrees/?$' "$MAIN/.gitignore"; then
+  printf '\n.worktrees/\n' >> "$MAIN/.gitignore"
+  err "WARN: appended '.worktrees/' to $MAIN/.gitignore (was missing)."
+fi
+
+# 2. Fetch trunk (read-only; never touches the main repo HEAD)
+git -C "$MAIN" fetch origin "$TRUNK" --quiet 2>>"$LOG" || err "WARN: git fetch origin $TRUNK failed — branching from possibly-stale local ref"
+
+# 3. Collision guard — a code worktree is NOT silently re-creatable. The caller's
+#    4a2 pre-check should have reset any orphan; if something is still here, fail
+#    loud rather than clobber.
+EXISTING="$(git -C "$MAIN" worktree list --porcelain | awk -v b="refs/heads/$BRANCH" '$1=="worktree"{p=$2} $1=="branch"&&$2==b{print p}')"
+if [ -n "$EXISTING" ]; then
+  fail "branch '$BRANCH' already has a worktree at '$EXISTING' (caller's idempotency pre-check should reset/resume before invoking this script)" 3
+fi
+if [ -e "$WT_ABS" ]; then
+  fail "worktree path '$WT_ABS' already exists on disk (stale orphan — caller must reset it first)" 3
+fi
+
+# 4. Create the worktree off origin/$TRUNK + stamp created_at AT creation
+git -C "$MAIN" worktree add "$WT_REL" -b "$BRANCH" "origin/$TRUNK" >>"$LOG" 2>&1 \
+  || fail "git worktree add failed (see $LOG)" 4
+M_CREATED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+# Provisional NON-terminal manifest — written the instant the worktree exists, so
+# that if this process is KILLED mid-install/build (e.g. the caller's background
+# timeout fires, or no `timeout` binary exists on this host so the build runs
+# unbounded) the manifest on disk still reads status:error / baseline:- . The
+# caller's disk gate (setup.md 6a) treats anything that is NOT a terminal
+# `status: ok` + `baseline: pass` as NOT-verified → fallback, never a false pass
+# on a half-built worktree whose node_modules merely happens to exist.
+M_STATUS="error"; M_ERROR="setup incomplete (worktree created, install/build not finished — process killed or interrupted)"
+write_manifest
+
+# 4b. Sync untracked backlog cards from main (created during /prd, not yet on trunk)
+if [ -d "$MAIN/$BACKLOG_DIR" ]; then
+  mkdir -p "$WT_ABS/$BACKLOG_DIR" 2>/dev/null || true
+  for CARD_FILE in "$MAIN/$BACKLOG_DIR"/*.yml; do
+    [ -e "$CARD_FILE" ] || continue
+    BN="$(basename "$CARD_FILE")"
+    [ -f "$WT_ABS/$BACKLOG_DIR/$BN" ] || cp "$CARD_FILE" "$WT_ABS/$BACKLOG_DIR/$BN" 2>/dev/null || true
+  done
+fi
+
+cd "$WT_ABS" || fail "cannot cd into worktree '$WT_ABS'" 4
+
+# 5. Install dependencies — NON-INTERACTIVE (stdin closed, CI=1). An install that
+#    blocks on a prompt is the bash equivalent of the model "going idle" — the
+#    exact failure this script eliminates; never reintroduce it via a prompt.
+err "… installing dependencies ($INSTALL_CMD)"
+if ! CI=1 bash -c "$INSTALL_CMD" </dev/null >>"$LOG" 2>&1; then
+  M_BASELINE="fail"; M_BLOG="$LOG"
+  fail "dependency install failed ($INSTALL_CMD) — see $LOG" 5
+fi
+
+# 6. Copy gitignored env artifacts (stack.env_files). FILES via plain cp
+#    (dereferences symlinks; never cp -P), DIRS via cp -R. Missing FILE → WARN,
+#    never abort (the baseline build gate is the real enforcement).
+primary_env=""
+copied_any=0
+for ef in "${ENV_FILES[@]:-}"; do
+  [ -n "$ef" ] || continue
+  src="$MAIN/$ef"; dest_dir="$(dirname "$ef")"
+  if [ -d "$src" ]; then
+    mkdir -p "$dest_dir"; rm -rf "$ef"
+    cp -R "$src" "$dest_dir"/ 2>/dev/null || true
+    [ -e "$ef" ] && copied_any=1 || err "WARN: env dir '$ef' present in main but copy failed."
+  elif [ -f "$src" ]; then
+    mkdir -p "$dest_dir"
+    if cp "$src" "$ef" 2>>"$LOG"; then copied_any=1; [ -z "$primary_env" ] && primary_env="$ef"; fi
+  else
+    err "WARN: env artifact '$ef' (stack.env_files) not found in $MAIN — the build may fail if it is required."
+  fi
+done
+ENVSYNCED="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+if [ "$copied_any" = 0 ] && [ "${#ENV_FILES[@]}" -gt 0 ]; then
+  err "WARN: NO env artifacts copied (none of: ${ENV_FILES[*]:-} exist in $MAIN)."
+fi
+
+# 7. Allocate a free port UNDER THE LOCK (registry-held ports + live listeners),
+#    then write a PROVISIONAL registry entry (buildVerified:false) so the port is
+#    reserved against concurrent /nw before the long build runs. The lock is held
+#    only across the cheap pick+write — never across npm install / build.
+PORT=""
+if acquire_lock; then trap release_lock EXIT; fi
+USED="$(registry_used_ports | tr '\n' ' ')"
+p="$PORT_MIN"
+while [ "$p" -le "$PORT_MAX" ]; do
+  if printf ' %s ' "$USED" | grep -q " $p " ; then p=$(( p + 1 )); continue; fi
+  if lsof -i :"$p" -sTCP:LISTEN >/dev/null 2>&1; then p=$(( p + 1 )); continue; fi
+  PORT="$p"; break
+done
+if [ -z "$PORT" ]; then
+  release_lock; trap - EXIT
+  M_BASELINE="fail"; M_BLOG="$LOG"
+  fail "no free port in ${PORT_MIN}-${PORT_MAX} (deterministic — recreating cannot fix)" 6
+fi
+M_PORT="$PORT"
+registry_upsert "$PORT" "$ENVSYNCED" "false"
+release_lock; trap - EXIT
+
+# 7b. Persist PORT into the primary copied env file (the dev server reads it).
+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" 2>/dev/null \
+    || sed -i "s/^PORT=.*/PORT=$PORT/" "$PORT_ENV_FILE" 2>/dev/null || true
+else
+  echo "PORT=$PORT" >> "$PORT_ENV_FILE" 2>/dev/null || true
+fi
+
+# 8. Assert git hooks are ACTIVE (best-effort WARN, never blocks)
+HOOK_SRC=""
+for d in .husky .githooks scripts/git-hooks githooks; do
+  if [ -d "$d" ] && ls "$d" 2>/dev/null | grep -qE '^(pre-commit|pre-push|commit-msg)$'; then HOOK_SRC="$d"; break; fi
+done
+if [ -n "$HOOK_SRC" ]; then
+  ACTIVE="$(git config --get core.hooksPath || echo .git/hooks)"
+  case "$ACTIVE" in
+    "$HOOK_SRC"|"$HOOK_SRC"/*|.husky/_) : ;;
+    *) err "WARN: git hooks INACTIVE — versioned hooks in '$HOOK_SRC' but core.hooksPath='$ACTIVE'. Fix: git config core.hooksPath $HOOK_SRC" ;;
+  esac
+fi
+
+# 9. Baseline — tsc/lint are report-but-continue; build is STOP-on-fail.
+#    The build runs under a HARD timeout so a hung/interactive build cannot stall
+#    the caller's pre-flight barrier forever.
+err "… baseline typecheck ($TC_TC)"
+CI=1 bash -c "$TC_TC" </dev/null >>"$LOG" 2>&1 || err "WARN: typecheck failed (report-but-continue — trunk should be clean; see $LOG)"
+err "… baseline lint ($TC_LINT)"
+CI=1 bash -c "$TC_LINT" </dev/null >>"$LOG" 2>&1 || err "WARN: lint failed (report-but-continue; see $LOG)"
+
+# Resolve a timeout binary (coreutils 'timeout', or gtimeout on macOS). If none,
+# run without one (best-effort) and WARN — better than aborting setup.
+TIMEOUT_BIN=""
+command -v timeout >/dev/null 2>&1 && TIMEOUT_BIN="timeout"
+[ -z "$TIMEOUT_BIN" ] && command -v gtimeout >/dev/null 2>&1 && TIMEOUT_BIN="gtimeout"
+
+err "… baseline build ($TC_BUILD, timeout ${BUILD_TIMEOUT}s)"
+if [ -n "$TIMEOUT_BIN" ]; then
+  CI=1 "$TIMEOUT_BIN" "$BUILD_TIMEOUT" bash -c "$TC_BUILD" </dev/null >>"$LOG" 2>&1
+  BUILD_RC=$?
+else
+  err "WARN: no 'timeout'/'gtimeout' binary — running build WITHOUT a hard timeout."
+  CI=1 bash -c "$TC_BUILD" </dev/null >>"$LOG" 2>&1
+  BUILD_RC=$?
+fi
+
+if [ "$BUILD_RC" -eq 124 ] && [ -n "$TIMEOUT_BIN" ]; then
+  M_BASELINE="timeout"; M_BLOG="$LOG"
+  # leave buildVerified:false in the registry (already provisional)
+  fail "baseline build TIMED OUT after ${BUILD_TIMEOUT}s — partial log at $LOG" 7
+elif [ "$BUILD_RC" -ne 0 ]; then
+  M_BASELINE="fail"; M_BLOG="$LOG"
+  fail "baseline build FAILED (do NOT fix here — the coder repairs it) — see $LOG" 7
+fi
+
+# 10. Build passed → flip buildVerified:true in the registry and finish clean.
+if acquire_lock; then trap release_lock EXIT; fi
+registry_upsert "$PORT" "$ENVSYNCED" "true"
+release_lock; trap - EXIT
+
+M_STATUS="ok"; M_ERROR="-"; M_BASELINE="pass"; M_BLOG="-"
+write_manifest
+err "✓ worktree ready: $WT_ABS (branch $BRANCH, port $PORT, baseline pass)"
+exit 0

package/framework/.claude/workflows/new-card-review.js

@@ -80,6 +80,7 @@ const FINDING = {
     evidence: { type: 'string', description: 'exact file:line + code quote' },
     minimal_fix_direction: { type: 'string' },
     domain: { enum: ['doc', 'security', 'migration', 'code', 'perf', 'test'], description: 'Domain-Override routing bucket' },
+    requires_action: { type: 'boolean', description: 'false = a VERIFIED observation that needs NO change anywhere (concern cleared / safe-as-is / advisory) — recorded for audit, NEVER routed to a writer. Omit (⇒ actionable) when a concrete edit is needed. If a change is needed but not by you (out of scope), keep true and say so in minimal_fix_direction (it surfaces as residual).' },
   },
 }
 const FINDINGS_SCHEMA = {
@@ -200,7 +201,8 @@ const codexPrompt =
   `Return codexAvailable:false ONLY if $REVIEW_FILE ends up containing "CODEX_NOT_FOUND" or stays empty after the FULL 10-minute window — NEVER because a single Bash call returned slowly.\n\n` +
   `${waveBrief}\n\n${baselineBrief}\n\n` +
   `For each finding return: finding_id, title, severity (BLOCKER|HIGH|MEDIUM|LOW), confidence (0-100), evidence (exact file:line + code quote), minimal_fix_direction, and domain (doc|security|migration|code|perf|test). ` +
-  `Run the mandatory false-positive check on every finding and suppress the unconvincing ones (your findings are treated as already FP-validated). Set codexAvailable:true when the review ran.`
+  `Run the mandatory false-positive check on every finding and suppress the unconvincing ones (your findings are treated as already FP-validated). ` +
+  `Then the actionability check: an observation you have VERIFIED needs NO change anywhere (the fix direction would be "no fix required" / "acceptable as-is" / "verified non-issue") is not work — set requires_action:false on it (it is recorded but never sent to a fixer), or simply do not emit it. Emit requires_action true/omitted ONLY when a concrete edit is needed. Set codexAvailable:true when the review ran.`
 
 const tcGateLines = [
   ['lint', tcCmds.lint], ['typecheck', tcCmds.typecheck], ['test', tcCmds.test],
@@ -218,12 +220,14 @@ function simplifyPrompt(c) {
     `  • Quality — redundant state, parameter sprawl, copy-paste with slight variation, leaky abstractions, stringly-typed code where enums exist, unnecessary JSX nesting, WHAT-comments / narration.\n` +
     `  • Efficiency — redundant computation, duplicate API calls, N+1, missed concurrency, hot-path bloat, missing change-detection guards, unbounded structures.\n\n` +
     `${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +
-    `Run a false-positive check on every finding and SUPPRESS the unconvincing ones (your surviving findings are treated as validated). Return findings with domain in {code, perf}. Flag only a finding you genuinely cannot resolve as confidence < 80.`
+    `Run a false-positive check on every finding and SUPPRESS the unconvincing ones (your surviving findings are treated as validated). ` +
+    `Then the actionability check: an observation you have VERIFIED needs NO change (the fix direction would be "no fix required" / "acceptable as-is" / "optional") is not work — set requires_action:false (recorded, never sent to a fixer), or do not emit it. Return findings with domain in {code, perf}. Flag only a finding you genuinely cannot resolve as confidence < 80.`
 }
 
 function securityPrompt(c) {
   return `AppSec review (read-only) over ONE card's committed diff — auth, permissions, secrets, webhooks, file upload, infra, multi-tenant isolation, injection. Security-sensitive paths: ${highRisk.join(', ') || '(none configured)'}.\n\n${cardScopeBrief(c)}\n\n${baselineBrief}\n\n` +
-    `You OWN the security domain end-to-end: run the mandatory false-positive check on every finding yourself and SUPPRESS the unconvincing ones — your surviving findings are treated as validated and are NOT re-judged by another agent. Flag only a finding you genuinely cannot resolve as confidence < 80. Return findings with domain in {security, migration}.`
+    `You OWN the security domain end-to-end: run the mandatory false-positive check on every finding yourself and SUPPRESS the unconvincing ones — your surviving findings are treated as validated and are NOT re-judged by another agent. ` +
+    `Then the actionability check: a control you have VERIFIED as safe-as-is needs NO change (the fix direction would be "no fix required" / "verified safe") — set requires_action:false on it (recorded for the security audit trail, never sent to a fixer), or do not emit it. Flag only a finding you genuinely cannot resolve as confidence < 80. Return findings with domain in {security, migration}.`
 }
 
 // Build the finder fan-out. Per-card: simplify (if runSimplify), security (if hasSecurityFiles).
@@ -273,12 +277,19 @@ for (const item of findResults) {
 if (!codexRan) {
   codexEngine = 'code-reviewer (fallback)'
   const fb = await agent(
-    `Codex was unavailable for this wave's code review. Run the FULL code review yourself over the wave diff, per ${protocolRef} (Phase 3.7).\n\n${waveBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied (your findings are treated as validated).`,
+    `Codex was unavailable for this wave's code review. Run the FULL code review yourself over the wave diff, per ${protocolRef} (Phase 3.7).\n\n${waveBrief}\n\n${baselineBrief}\n\nReturn findings using the schema fields, with a self false-positive check applied (your findings are treated as validated). An observation you VERIFIED needs NO change (fix direction "no fix required" / "acceptable as-is") is not work — set requires_action:false (recorded, never sent to a fixer), or do not emit it.`,
     { label: 'code-reviewer (fallback)', phase: 'Discovery', agentType: 'code-reviewer', schema: FINDINGS_SCHEMA }
   )
   if (fb && Array.isArray(fb.findings)) raw.push(...fb.findings.map((f) => ({ ...f, source: 'code-reviewer', preValidated: true })))
 }
 
+// Globally-unique finding_id at the fan-in. Finders number F### INDEPENDENTLY, so a Codex F003 and
+// a security F003 collide. The Fix-phase bookkeeping (appliedIds / unresolvedIds / codeResidual /
+// bucket) keys on finding_id with FLAT Sets, so a collision cross-contaminates: one finder's
+// `unresolved` id drags another finder's APPLIED same-id finding into residual (the empty-coder
+// re-spawn bug). Prefix source + running index → uniqueness without losing the human-readable id.
+raw.forEach((f, i) => { f.finding_id = `${f.source || 'src'}#${i}:${f.finding_id || ('F' + i)}` })
+
 // ───────────────────────────────────────────────────────────────────────────
 // Phase Verify — specialist-owned validation (parity with new-final-review.js F.4)
 // ───────────────────────────────────────────────────────────────────────────
@@ -330,16 +341,29 @@ const isDoc = (f) => /doc|wiki|ssot|readme/.test(String(f.domain).toLowerCase())
 // migration/test → coder), so match the exact 'security' domain, not the broader verifier regex.
 const isSecurity = (f) => String(f.domain).toLowerCase() === 'security'
 const isManual = (f) => f.classification === 'NEEDS_MANUAL_CONFIRMATION'
+// Actionability gate: a VERIFIED finding that needs NO change must NOT reach a writer (it floods the
+// fix pass with no-ops). Honoured ONLY for MED/LOW — a BLOCKER/HIGH is always actionable (the flag
+// can never suppress a blocker; a cross-wave HIGH like "don't merge before the consumer cards" stays
+// actionable → surfaces as residual). Signal: finder flag requires_action:false, OR a conservative
+// regex backstop on the fix direction for when the model omitted the flag. Never a silent drop —
+// no-action findings are logged + counted, just excluded from the writer partitions.
+const NO_ACTION_RE = /(^|[.\s(])(no\s+(fix|change|action)\s+(is\s+)?(required|needed)|none\s+(needed|required)|not\s+a\s+(defect|bug|correctness\s+bug)|acceptable\s+as[-\s]is|verified\s+(safe|non[-\s]issue)|no\s+action\s+(needed|required))([.\s,;)]|$)/i
+const isNoAction = (f) => (f.severity !== 'BLOCKER' && f.severity !== 'HIGH') &&
+  (f.requires_action === false || NO_ACTION_RE.test(String(f.minimal_fix_direction || '')))
 // Partition `surviving` (= VERIFIED + NEEDS_MANUAL; FALSE_POSITIVE already dropped) with NO overlap:
 //   securityFix   = VERIFIED security → security-reviewer applies (it owns the security invariants).
 //   actionable    = VERIFIED non-doc non-security → the coder fixes these.
 //   docResidual   = VERIFIED doc      → the skill runs doc-reviewer post-E2E on final code.
 //   manualResidual= NEEDS_MANUAL any  → human gate, owned by the skill (a doc-manual must NOT be
 //                   silently auto-re-reviewed: it carries its needs-manual classification out).
-const securityFix = surviving.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && isSecurity(f))
-const actionable = surviving.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && !isSecurity(f))
-const docResidual = surviving.filter((f) => f.classification === 'VERIFIED' && isDoc(f))
+// No-action VERIFIED findings: recorded + counted, excluded from every writer partition.
+const noAction = surviving.filter((f) => f.classification === 'VERIFIED' && isNoAction(f))
+const noActionSet = new Set(noAction)
+const securityFix = surviving.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && isSecurity(f) && !noActionSet.has(f))
+const actionable = surviving.filter((f) => f.classification === 'VERIFIED' && !isDoc(f) && !isSecurity(f) && !noActionSet.has(f))
+const docResidual = surviving.filter((f) => f.classification === 'VERIFIED' && isDoc(f) && !noActionSet.has(f))
 const manualResidual = surviving.filter(isManual)
+for (const f of noAction) log(`Review: no-action finding recorded (not routed to a writer): [${f.finding_id}] ${f.severity} ${f.domain} — ${f.title} (${f.requires_action === false ? 'requires_action:false' : 'no-action-inferred'})`)
 
 const SKIP_CHECKS = { lint: 'SKIP', tsc: 'SKIP', build: 'SKIP' }
 
@@ -360,7 +384,7 @@ async function applyFixPass(findings, writer, label, role) {
     findings.map((f) => `- [${f.finding_id}] (${f.card || '?'} / ${f.domain} / ${f.severity}) ${f.title}\n    evidence: ${f.evidence}\n    direction: ${f.minimal_fix_direction}`).join('\n') +
     `\n\nAfter applying: run \`${tc('lint', 'npm run lint')}\` and (when the project uses typescript) \`${tc('typecheck', 'npx tsc --noEmit')}\` and \`${tc('build', 'npm run build')}\` in the worktree. If a check fails because of an edit you made, fix the regression — at most 2 retries — staying within the allowed files. ` +
     `Do NOT commit. Do NOT git stash (refs/stash is shared across worktrees). ` +
-    `Return: applied (finding_ids you fixed), unresolved (finding_ids you could NOT fix within the allowed files / 2 retries), and checks (PASS/FAIL/SKIP for lint, tsc, build).`
+    `Return: applied (finding_ids you fixed — list a finding here if you MADE the edit, even when the build stays red for reasons OUTSIDE this finding / your ownership, e.g. a known cross-wave cascade; the build status is reported separately in checks), unresolved (finding_ids you could NOT fix within the allowed files / 2 retries — i.e. the EDIT itself could not be made), and checks (PASS/FAIL/SKIP for lint, tsc, build).`
   const r = await agent(fixBrief, { label, phase: 'Fix', agentType: writer, schema: FIX_SCHEMA })
   // Normalize: the agent may die (null) or return a truthy object missing fields.
   const res = (r && typeof r === 'object') ? r : { applied: [], unresolved: findings.map((f) => f.finding_id), checks: { ...SKIP_CHECKS } }
@@ -407,6 +431,7 @@ const summary = makeSummary({
   cards: cards.length,
   totalFindings: raw.length,
   verified: surviving.filter((f) => f.classification === 'VERIFIED').length,
+  noAction: noAction.length,                 // VERIFIED-but-no-change findings: recorded, never sent to a writer
   falsePositive: classified.filter((f) => f.classification === 'FALSE_POSITIVE').length,
   needsManual: manualResidual.length,
   fixesApplied: appliedIds.size,
@@ -418,7 +443,7 @@ const summary = makeSummary({
   blockers: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'BLOCKER').length,
   highs: surviving.filter((f) => f.classification === 'VERIFIED' && f.severity === 'HIGH').length,
 })
-log(`Wave review done: ${summary.fixesApplied} fixed, ${summary.codeResidual} code-residual, ${summary.docResidual} doc-residual, ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${checksFailed ? ', post-fix checks FAILED' : ''}. Engine: ${codexEngine}.`)
+log(`Wave review done: ${summary.fixesApplied} fixed, ${summary.codeResidual} code-residual, ${summary.docResidual} doc-residual, ${summary.noAction} no-action (recorded), ${summary.needsManual} needs-manual, ${summary.failingGates.length} failing gate(s)${checksFailed ? ', post-fix checks FAILED' : ''}. Engine: ${codexEngine}.`)
 
 return { codexEngine, perCard, gateTable, summary }
 
@@ -426,7 +451,7 @@ return { codexEngine, perCard, gateTable, summary }
 function asArr(x) { return Array.isArray(x) ? x.filter(Boolean) : [] }
 function dedupe(xs) { return Array.from(new Set(asArr(xs))) }
 function makeSummary(o) {
-  return Object.assign({ cards: 0, totalFindings: 0, verified: 0, falsePositive: 0, needsManual: 0, fixesApplied: 0, docResidual: 0, codeResidual: 0, qaRan: false, checksFailed: false, failingGates: [], blockers: 0, highs: 0 }, o || {})
+  return Object.assign({ cards: 0, totalFindings: 0, verified: 0, noAction: 0, falsePositive: 0, needsManual: 0, fixesApplied: 0, docResidual: 0, codeResidual: 0, qaRan: false, checksFailed: false, failingGates: [], blockers: 0, highs: 0 }, o || {})
 }
 function slimFinding(f) {
   return { finding_id: f.finding_id, title: f.title, severity: f.severity, domain: f.domain, evidence: f.evidence, minimal_fix_direction: f.minimal_fix_direction, classification: f.classification, card: f.card }