cleargate 0.14.0 → 0.15.1

package/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -63,6 +63,15 @@
  *   CLEARGATE_SKIP_BUNDLE_CHECK=1    — skip Step 3.5 bundle generation + size check entirely
  *                                      (CR-036 test seam; analogous to CLEARGATE_SKIP_MERGE_CHECK).
  *                                      Never use in production — Step 3.5 is v2-fatal in production.
+ *   CLEARGATE_SKIP_DEFERRED_VERIFY_CHECK=1 — skip Step 2.9 entirely (test environments where
+ *                                            deferred-verification state is irrelevant; mirrors
+ *                                            CLEARGATE_SKIP_WORKTREE_CHECK).
+ *   CLEARGATE_FORCE_DEFERRED_VERIFY=<json> — inject a JSON map of deferred-verify state without
+ *                                            reading real story files or result artifacts (mirrors
+ *                                            CLEARGATE_FORCE_WORKTREE_PATHS). Shape:
+ *                                            { "<STORY-ID>": { declared:[{command,blocks}],
+ *                                              result:"green"|"red"|"unrun"|null } }
+ *                                            Used to exercise FAIL/PASS/no-op paths in the node:test.
  */
 
 import fs from 'node:fs';
@@ -700,6 +709,224 @@ async function main() {
     }
   }
 
+  // ── Step 2.9: Deferred-Verification Close Gate (CR-082) ─────────────────────
+  // Block close if any story in this sprint declares a deferred_verification entry
+  // with blocks: close and does NOT have a matching green result artifact.
+  // NO-OP when no story declares any deferred_verification (the common case — SPRINT-34's path).
+  // Fail-open if story-file scan throws (delivery dir absent) — print skip, continue.
+  // Test seams: CLEARGATE_SKIP_DEFERRED_VERIFY_CHECK=1 bypasses entirely;
+  //             CLEARGATE_FORCE_DEFERRED_VERIFY=<json> injects state without reading files.
+  process.stdout.write('Step 2.9: checking deferred verifications...\n');
+  {
+    if (process.env.CLEARGATE_SKIP_DEFERRED_VERIFY_CHECK === '1') {
+      process.stdout.write('Step 2.9 skipped: CLEARGATE_SKIP_DEFERRED_VERIFY_CHECK=1 set (test seam).\n');
+    } else {
+      /**
+       * Parse minimal frontmatter from a markdown file: returns an object of
+       * key: value pairs from the YAML block between the first two `---` lines.
+       * List fields (e.g. deferred_verification: [...]) are returned as raw strings.
+       * @param {string} raw
+       * @returns {Record<string,string>}
+       */
+      function parseFrontmatterFields(raw) {
+        const fm = raw.match(/^---\n([\s\S]*?)\n---/);
+        if (!fm) return {};
+        const fields = {};
+        for (const line of fm[1].split('\n')) {
+          const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*(.*)/);
+          if (m) fields[m[1]] = m[2].trim();
+        }
+        return fields;
+      }
+
+      /**
+       * Extract the deferred_verification list from raw frontmatter text.
+       * Looks for the multi-line YAML list following `deferred_verification:`.
+       * Returns an array of { description?, command, blocks } objects, or [].
+       * @param {string} raw
+       * @returns {Array<{description?: string, command: string, blocks: string}>}
+       */
+      function parseDeferredVerifications(raw) {
+        const fm = raw.match(/^---\n([\s\S]*?)\n---/);
+        if (!fm) return [];
+        const block = fm[1];
+        // Find the deferred_verification key and its value
+        const keyIdx = block.indexOf('deferred_verification:');
+        if (keyIdx === -1) return [];
+        const afterKey = block.slice(keyIdx + 'deferred_verification:'.length);
+        const inlineVal = afterKey.match(/^\s*\[([^\]]*)\]/);
+        if (inlineVal) {
+          const inner = inlineVal[1].trim();
+          if (!inner) return []; // empty list []
+        }
+        // Parse YAML-list items: lines starting with "- " at same or deeper indent
+        // For simplicity: if the inline value is empty or the list is multi-line,
+        // scan for list entries. A minimal deferred_verification entry has a `command:` field.
+        const lines = afterKey.split('\n');
+        const entries = [];
+        let currentEntry = null;
+        for (const line of lines) {
+          const listItem = line.match(/^(\s*)-\s+(.*)/);
+          const keyVal = line.match(/^\s+([a-zA-Z_]+)\s*:\s*(.*)/);
+          if (listItem) {
+            if (currentEntry) entries.push(currentEntry);
+            currentEntry = {};
+            const rest = listItem[2].trim();
+            if (rest.startsWith('{')) {
+              // Inline object: { description: ..., command: ..., blocks: ... }
+              const descM = rest.match(/description\s*:\s*([^,}]+)/);
+              const cmdM = rest.match(/command\s*:\s*([^,}]+)/);
+              const blkM = rest.match(/blocks\s*:\s*([^,}]+)/);
+              if (descM) currentEntry.description = descM[1].trim().replace(/['"]/g, '');
+              if (cmdM) currentEntry.command = cmdM[1].trim().replace(/['"]/g, '');
+              if (blkM) currentEntry.blocks = blkM[1].trim().replace(/['"]/g, '');
+            }
+          } else if (keyVal && currentEntry !== null) {
+            const k = keyVal[1].trim();
+            const v = keyVal[2].trim().replace(/['"]/g, '');
+            currentEntry[k] = v;
+          } else if (line.match(/^[a-zA-Z_]/) && !line.match(/^\s/)) {
+            // Hit a top-level key — end of list
+            break;
+          }
+        }
+        if (currentEntry) entries.push(currentEntry);
+        // Filter to only entries that have a command (valid entries)
+        return entries.filter((e) => e && (e.command || e.blocks));
+      }
+
+      // Determine the declared deferred-verify entries per story
+      /** @type {Record<string, {declared: Array<{command:string,blocks:string}>, result: string|null}>} */
+      let deferredMap = {};
+      let storyFileScanAvailable = true;
+
+      if (process.env.CLEARGATE_FORCE_DEFERRED_VERIFY) {
+        // Test seam: inject state without reading real story files
+        try {
+          deferredMap = JSON.parse(process.env.CLEARGATE_FORCE_DEFERRED_VERIFY);
+        } catch (parseErr) {
+          process.stderr.write(
+            `Step 2.9 warning: CLEARGATE_FORCE_DEFERRED_VERIFY is not valid JSON: ${/** @type {Error} */ (parseErr).message}\n`
+          );
+          storyFileScanAvailable = false;
+        }
+      } else {
+        // Scan delivery/pending-sync/ + delivery/archive/ for sprint's story files
+        try {
+          const deliveryBase = path.join(REPO_ROOT, '.cleargate', 'delivery');
+          const dirsToScan = [
+            path.join(deliveryBase, 'pending-sync'),
+            path.join(deliveryBase, 'archive'),
+          ];
+          for (const dir of dirsToScan) {
+            if (!fs.existsSync(dir)) continue;
+            for (const fname of fs.readdirSync(dir)) {
+              if (!fname.endsWith('.md')) continue;
+              const fpath = path.join(dir, fname);
+              let raw;
+              try {
+                raw = fs.readFileSync(fpath, 'utf8');
+              } catch {
+                continue;
+              }
+              const fields = parseFrontmatterFields(raw);
+              if (fields['sprint_cleargate_id'] !== sprintId) continue;
+              // This file belongs to the sprint — check for deferred_verification
+              const entries = parseDeferredVerifications(raw);
+              const storyId = fields['story_id'] || fields['cr_id'] || fname.replace('.md', '');
+              if (entries.length > 0) {
+                deferredMap[storyId] = { declared: entries, result: null };
+              }
+            }
+          }
+        } catch (scanErr) {
+          storyFileScanAvailable = false;
+          process.stdout.write(
+            `Step 2.9 skipped: story-file scan unavailable (non-fatal): ${/** @type {Error} */ (scanErr).message}\n`
+          );
+        }
+      }
+
+      if (!storyFileScanAvailable) {
+        // fail-open: scan threw, already printed message above
+      } else {
+        // Check: any stories with deferred_verification declared?
+        const storiesWithDeferred = Object.keys(deferredMap);
+        if (storiesWithDeferred.length === 0) {
+          // NO-OP: no deferred verifications — silent pass (SPRINT-34's own close path)
+          process.stdout.write('Step 2.9 passed: no deferred verifications declared.\n');
+        } else {
+          const deferred_verify_dir = path.join(sprintDir, 'deferred-verify');
+          const failures = [];
+
+          for (const storyId of storiesWithDeferred) {
+            const { declared, result: forcedResult } = deferredMap[storyId];
+            const closeEntries = declared.filter(
+              (e) => !e.blocks || e.blocks === 'close'
+            );
+            if (closeEntries.length === 0) continue;
+
+            if (forcedResult !== undefined && forcedResult !== null) {
+              // Test seam: result injected via CLEARGATE_FORCE_DEFERRED_VERIFY
+              if (forcedResult !== 'green') {
+                for (const entry of closeEntries) {
+                  failures.push({ storyId, command: entry.command, reason: forcedResult ?? 'unrun' });
+                }
+              }
+            } else {
+              // Read result artifact from deferred-verify/<STORY-ID>.json
+              const resultFile = path.join(deferred_verify_dir, `${storyId}.json`);
+              if (!fs.existsSync(resultFile)) {
+                for (const entry of closeEntries) {
+                  failures.push({ storyId, command: entry.command, reason: 'no result file' });
+                }
+              } else {
+                let resultJson;
+                try {
+                  resultJson = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+                } catch {
+                  for (const entry of closeEntries) {
+                    failures.push({ storyId, command: entry.command, reason: 'unreadable result file' });
+                  }
+                  continue;
+                }
+                if (resultJson.status !== 'green' || resultJson.exit_code !== 0) {
+                  for (const entry of closeEntries) {
+                    failures.push({
+                      storyId,
+                      command: entry.command,
+                      reason: `status=${resultJson.status ?? 'unknown'} exit_code=${resultJson.exit_code ?? 'unknown'}`,
+                    });
+                  }
+                }
+              }
+            }
+          }
+
+          if (failures.length > 0) {
+            process.stderr.write(
+              `Step 2.9 failed: ${failures.length} deferred verification(s) not green:\n`
+            );
+            for (const f of failures) {
+              process.stderr.write(
+                `  - ${f.storyId}: command="${f.command}" reason=${f.reason}\n`
+              );
+            }
+            process.stderr.write(
+              `  Run each command, write the result to ${deferred_verify_dir}/<STORY-ID>.json,\n` +
+              `  then re-run close_sprint.mjs.\n`
+            );
+            process.exit(1);
+          } else {
+            process.stdout.write(
+              `Step 2.9 passed: all ${storiesWithDeferred.length} story/stories' deferred verifications are green.\n`
+            );
+          }
+        }
+      }
+    }
+  }
+
   // ── Step 3: Invoke prefill_report.mjs ─────────────────────────────────────
   process.stdout.write('Step 3: running prefill_report.mjs...\n');
   try {

package/templates/cleargate-planning/.cleargate/scripts/gate-checks.json

@@ -1,15 +1,16 @@
 {
   "schema_version": 1,
   "qa": {
-    "typecheck": "cd cleargate-cli && npm run typecheck",
+    "typecheck": "",
     "debug_patterns": ["console.log", "console.debug", "debugger"],
     "todo_patterns": ["TODO", "FIXME", "XXX"],
-    "test": "cd cleargate-cli && npm test"
+    "test": ""
   },
   "arch": {
-    "typecheck": "cd cleargate-cli && npm run typecheck",
+    "typecheck": "",
     "new_deps_check": true,
     "stray_env_files": [".env", ".env.local", ".env.production"],
-    "file_count_report": true
+    "file_count_report": true,
+    "qa_red_lint": true
   }
 }

package/templates/cleargate-planning/.cleargate/scripts/init_sprint.mjs

@@ -147,9 +147,62 @@ function main() {
   }
 
   const now = new Date().toISOString();
+
+  // --- CR-078 F2: Ingest SDR lane assignments ---
+  // Read lane assignments from plans/waves.json (canonical machine-readable source).
+  // Falls back to parsing the Sprint Plan §2.4 Lane Audit table when waves.json is absent.
+  // Emits a WARN (not a hard fail) when neither source declares any lane.
+  const wavesJsonPath = path.join(sprintDir, 'plans', 'waves.json');
+  let laneAssignments = {};
+  let laneSourceFound = false;
+
+  // Try waves.json first
+  if (fs.existsSync(wavesJsonPath)) {
+    try {
+      const wavesData = JSON.parse(fs.readFileSync(wavesJsonPath, 'utf8'));
+      // waves.json may carry a top-level `lane_assignments: { "STORY-ID": "fast"|"standard" }` map
+      if (wavesData.lane_assignments && typeof wavesData.lane_assignments === 'object') {
+        laneAssignments = wavesData.lane_assignments;
+        laneSourceFound = Object.keys(laneAssignments).length > 0;
+      }
+    } catch (err) {
+      process.stderr.write(`WARN: could not parse plans/waves.json: ${err.message}\n`);
+    }
+  }
+
+  // Fallback: parse Sprint Plan §2.4 Lane Audit table
+  if (!laneSourceFound && sprintFilePath) {
+    try {
+      const planContent = fs.readFileSync(sprintFilePath, 'utf8');
+      // Match the §2.4 Lane Audit table rows: `| Story-ID | lane | rationale |`
+      // Accepts both backtick-wrapped and bare story IDs in the first column.
+      const tableRowRe = /^\|\s*`?([A-Z][-A-Z0-9]*(?:-\d+)?(?:-\d+)?)`?\s*\|\s*(fast|standard)\s*\|/gm;
+      let match;
+      while ((match = tableRowRe.exec(planContent)) !== null) {
+        const storyId = match[1].trim();
+        const lane = match[2].trim();
+        laneAssignments[storyId] = lane;
+        laneSourceFound = true;
+      }
+    } catch (err) {
+      process.stderr.write(`WARN: could not read sprint plan for lane audit: ${err.message}\n`);
+    }
+  }
+
+  if (!laneSourceFound) {
+    process.stderr.write(
+      `WARN: no lane assignments found (no plans/waves.json lane_assignments and no §2.4 Lane Audit table) — all stories default to standard\n`
+    );
+  }
+
   const stories = {};
   for (const id of storyIds) {
     const carry = preserved[id] || {};
+    // Apply SDR lane assignment when available; carry-over lanes take precedence over
+    // sdr-lane-audit (they were already explicitly set in the previous sprint).
+    const sdrLane = laneAssignments[id];
+    const assignedLane = carry.lane ?? sdrLane ?? 'standard';
+    const assignedBy = carry.lane_assigned_by ?? (sdrLane ? 'sdr-lane-audit' : 'migration-default');
     stories[id] = {
       state: carry.state ?? 'Ready to Bounce',
       qa_bounces: carry.qa_bounces ?? 0,
@@ -157,8 +210,8 @@ function main() {
       worktree: carry.worktree ?? null,
       updated_at: now,
       notes: carry.notes ?? '',
-      lane: carry.lane ?? 'standard',
-      lane_assigned_by: carry.lane_assigned_by ?? 'migration-default',
+      lane: assignedLane,
+      lane_assigned_by: assignedBy,
       lane_demoted_at: carry.lane_demoted_at ?? null,
       lane_demotion_reason: carry.lane_demotion_reason ?? null,
     };
@@ -234,6 +287,26 @@ function main() {
     }
   }
 
+  // --- CR-078 F1: Write .active sentinel (FINAL step) ---
+  // Atomically set <projectRoot>/.cleargate/sprint-runs/.active to the sprint ID,
+  // mirroring the state.json atomic-write idiom (tmp + rename).
+  // Emits a one-line WARN when the prior .active is non-empty and differs from this sprint.
+  const activeFile = path.join(REPO_ROOT, '.cleargate', 'sprint-runs', '.active');
+  let priorActive = '';
+  try {
+    priorActive = fs.readFileSync(activeFile, 'utf8').trim();
+  } catch {
+    // File absent or unreadable — treat as empty; non-fatal
+  }
+  if (priorActive && priorActive !== sprintId) {
+    process.stderr.write(
+      `WARN: .active was ${priorActive}, overwriting with ${sprintId} — prior sprint may not have been closed\n`
+    );
+  }
+  const activeTmp = `${activeFile}.tmp.${process.pid}`;
+  fs.writeFileSync(activeTmp, sprintId + '\n', 'utf8');
+  fs.renameSync(activeTmp, activeFile);
+
   process.stdout.write(`Initialized state.json for sprint ${sprintId} with ${storyIds.length} stories\n`);
 }
 

package/templates/cleargate-planning/.cleargate/scripts/pre_gate_common.sh

@@ -178,6 +178,54 @@ append_ld_event() {
   fi
 }
 
+# ---------------------------------------------------------------------------
+# read_provision_config <config_yml_path>
+# Reads the worktree.provision_config list from config.yml (CR-079).
+# Returns one entry per line. Defaults to ".env" if absent/unset.
+# Single source of truth: both provision_worktree_config.sh and
+# pre_gate_runner.sh source this function so provisioning and exemption
+# always use the same list.
+# YAML read strategy: awk extracts lines indented under
+# "provision_config:" until the next non-list line or EOF.
+# Node is available but the awk approach keeps it dependency-light and
+# avoids a full YAML parse.
+# ---------------------------------------------------------------------------
+read_provision_config() {
+  local config_yml="${1:-}"
+  if [[ -z "${config_yml}" || ! -f "${config_yml}" ]]; then
+    # No config.yml — return the default list
+    printf '.env\n'
+    return
+  fi
+
+  # Extract the sequence items under "provision_config:" using awk.
+  # Handles YAML like:
+  #   worktree:
+  #     provision_config:
+  #       - .env
+  #       - .env.local
+  # Stops on the first line that is NOT an indented "  - <value>" after
+  # the provision_config: key.
+  local extracted
+  extracted="$(awk '
+    /^[[:space:]]*provision_config:/ { in_list=1; next }
+    in_list && /^[[:space:]]*-[[:space:]]+/ {
+      sub(/^[[:space:]]*-[[:space:]]+/, "")
+      sub(/[[:space:]]*$/, "")
+      print
+      next
+    }
+    in_list { in_list=0 }
+  ' "${config_yml}" 2>/dev/null || true)"
+
+  if [[ -z "${extracted}" ]]; then
+    # Key absent or empty — default to .env
+    printf '.env\n'
+  else
+    printf '%s\n' "${extracted}"
+  fi
+}
+
 # ---------------------------------------------------------------------------
 # diff_package_json <worktree_path> <branch>
 # Prints new runtime deps (non-dev) introduced vs <branch>^.

package/templates/cleargate-planning/.cleargate/scripts/pre_gate_runner.sh

@@ -41,6 +41,11 @@ if [[ ! -d "$WORKTREE" ]]; then
   exit 2
 fi
 
+# F5 — normalize WORKTREE to an absolute path so that REPORT_FILE and every
+# downstream non-subshell `cd "$WORKTREE"` resolve correctly regardless of
+# whether the caller passed a relative or absolute path (CR-080).
+WORKTREE="$(cd "$WORKTREE" && pwd)"
+
 # ---------------------------------------------------------------------------
 # Locate gate-checks.json — auto-seed if missing
 # ---------------------------------------------------------------------------
@@ -255,11 +260,34 @@ run_arch() {
     try { JSON.parse('${stray_env_json}').forEach(p => console.log(p)); } catch(e) {}
   " 2>/dev/null)
 
+  # Read the provisioned-config exemption list (CR-079 single source).
+  # config.yml lives two directories above SCRIPT_DIR (.cleargate/scripts/../..).
+  local CONFIG_YML
+  CONFIG_YML="$(cd "${SCRIPT_DIR}/../.." && pwd)/.cleargate/config.yml"
+  local provisioned_config=()
+  while IFS= read -r _pline; do
+    [[ -z "$_pline" ]] || provisioned_config+=("$_pline")
+  done < <(read_provision_config "${CONFIG_YML}")
+
+  # Helper: returns 0 (true) if a pattern is in the provisioned-config list.
+  is_provisioned() {
+    local _pat="$1"
+    local _p
+    for _p in "${provisioned_config[@]:-}"; do
+      [[ "$_p" = "$_pat" ]] && return 0
+    done
+    return 1
+  }
+
   local stray_found=0
   local stray_details=""
   for pat in "${stray_patterns[@]:-}"; do
     [[ -z "$pat" ]] && continue
-    if [[ -f "${WORKTREE}/${pat}" ]]; then
+    if [[ -f "${WORKTREE}/${pat}" || -L "${WORKTREE}/${pat}" ]]; then
+      # Skip patterns that are in the provisioned-config list (CR-079 exemption).
+      if is_provisioned "${pat}"; then
+        continue
+      fi
       stray_details+="${pat}"$'\n'
       stray_found=1
     fi
@@ -284,6 +312,34 @@ run_arch() {
         echo "  ${dir}: ${count} files" >> "$REPORT_FILE"
       done
   fi
+
+  # 5. QA-Red semantic fixture lint (CR-081)
+  # Glob red test files under the worktree, run qa_red_lint.mjs.
+  # Gate behind arch.qa_red_lint config key (default true).
+  # Uses ABSOLUTE paths — no cd (avoids cwd-leak per FLASHCARD #pre-gate #cwd-leak).
+  # Uses grep -q (not grep -c || echo 0 — avoids double-count hazard per FLASHCARD #test-harness #bash).
+  local qa_red_lint_enabled
+  qa_red_lint_enabled="$(read_config_field "arch.qa_red_lint" "$CONFIG_FILE")"
+  # Default to enabled when key is absent (empty string → treat as true)
+  if [[ -z "$qa_red_lint_enabled" || "$qa_red_lint_enabled" == "true" ]]; then
+    local lint_script="${SCRIPT_DIR}/qa_red_lint.mjs"
+    if [[ -f "$lint_script" ]]; then
+      local lint_out lint_exit
+      lint_exit=0
+      lint_out="$(node "${lint_script}" "${WORKTREE}" 2>&1)" || lint_exit=$?
+      if [[ $lint_exit -eq 0 ]]; then
+        record_result "$REPORT_FILE" "qa_red_lint" "PASS" "no semantic fixture issues"
+      else
+        record_result "$REPORT_FILE" "qa_red_lint" "FAIL" "$(echo "$lint_out" | head -5 | tr '\n' '|')"
+        echo "$lint_out" >> "$REPORT_FILE"
+        OVERALL_EXIT=1
+      fi
+    else
+      record_result "$REPORT_FILE" "qa_red_lint" "INFO" "skipped (qa_red_lint.mjs not found at ${lint_script})"
+    fi
+  else
+    record_result "$REPORT_FILE" "qa_red_lint" "INFO" "skipped (arch.qa_red_lint=false in config)"
+  fi
 }
 
 # ---------------------------------------------------------------------------

package/templates/cleargate-planning/.cleargate/scripts/provision_worktree_config.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# provision_worktree_config.sh — Provision configured gitignored config into a story worktree.
+# Usage: provision_worktree_config.sh <worktree-path> [--mode symlink|copy]
+#
+# Provisions the roots listed in config.yml worktree.provision_config (default [".env"])
+# into the given worktree path. Symlink mode (default) creates an absolute symlink so
+# the target's build/tests load their config in-worktree without a manual step.
+# Copy mode copies the file (use when the worktree must hold a divergent config).
+#
+# Idempotent: skips roots already present in the worktree.
+# No-op (INFO, exit 0): skips roots absent at the repo root (not an error).
+#
+# Absolute-path safety: repo root resolved via `git rev-parse --show-toplevel`
+# from the SCRIPT's own directory — NOT $PWD — to avoid the doubled-cwd hazard
+# (cf. FLASHCARD #pre-gate #cwd-leak: cwd in a worktree differs from repo root).
+#
+# Part of CR-079: F4 fix (provision gitignored config) + F7 fix (the provisioned
+# .env is exempted from the stray_env_files scan; see pre_gate_runner.sh + the
+# read_provision_config() single-source helper in pre_gate_common.sh).
+#
+# macOS bash 3.2 portable.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source shared helpers (read_provision_config lives here).
+# shellcheck source=pre_gate_common.sh
+source "${SCRIPT_DIR}/pre_gate_common.sh"
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+if [[ $# -lt 1 ]]; then
+  echo "Usage: provision_worktree_config.sh <worktree-path> [--mode symlink|copy]" >&2
+  exit 2
+fi
+
+WORKTREE_PATH="$1"
+shift
+
+# Default mode from config.yml worktree.provision_mode; flag overrides.
+PROVISION_MODE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      if [[ $# -lt 2 ]]; then
+        echo "provision_worktree_config.sh: --mode requires a value (symlink|copy)" >&2
+        exit 2
+      fi
+      PROVISION_MODE="$2"
+      shift 2
+      ;;
+    *)
+      echo "provision_worktree_config.sh: unknown argument '$1'" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -n "${PROVISION_MODE}" && "${PROVISION_MODE}" != "symlink" && "${PROVISION_MODE}" != "copy" ]]; then
+  echo "provision_worktree_config.sh: --mode must be 'symlink' or 'copy', got '${PROVISION_MODE}'" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Validate worktree path
+# ---------------------------------------------------------------------------
+if [[ ! -d "${WORKTREE_PATH}" ]]; then
+  echo "provision_worktree_config.sh: worktree path does not exist: ${WORKTREE_PATH}" >&2
+  exit 2
+fi
+
+# Resolve ABSOLUTE worktree path (guard against relative paths passed by caller).
+WORKTREE_ABS="$(cd "${WORKTREE_PATH}" && pwd)"
+
+# ---------------------------------------------------------------------------
+# Resolve repo root ABSOLUTELY from the script's own directory.
+# This is critical: $PWD in a worktree context points to the worktree, not
+# the repo root, causing doubled-cwd hazard if used for resolution.
+# ---------------------------------------------------------------------------
+REPO_ROOT="$(git -C "${SCRIPT_DIR}" rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "${REPO_ROOT}" ]]; then
+  echo "provision_worktree_config.sh: cannot resolve repo root from ${SCRIPT_DIR}" >&2
+  exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Read config.yml: provision_mode (if not set via flag)
+# ---------------------------------------------------------------------------
+CONFIG_YML="${REPO_ROOT}/.cleargate/config.yml"
+
+if [[ -z "${PROVISION_MODE}" ]]; then
+  if [[ -f "${CONFIG_YML}" ]]; then
+    # Extract provision_mode from config.yml using awk.
+    # YAML line looks like:  provision_mode: symlink
+    _raw_mode="$(awk '/^[[:space:]]*provision_mode:[[:space:]]/ {
+      sub(/^[[:space:]]*provision_mode:[[:space:]]*/, "")
+      sub(/[[:space:]]*#.*$/, "")
+      sub(/[[:space:]]*$/, "")
+      print; exit
+    }' "${CONFIG_YML}" 2>/dev/null || true)"
+    if [[ "${_raw_mode}" = "copy" ]]; then
+      PROVISION_MODE="copy"
+    else
+      PROVISION_MODE="symlink"
+    fi
+  else
+    PROVISION_MODE="symlink"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Read the provisioned-config list (single source: read_provision_config).
+# ---------------------------------------------------------------------------
+provision_roots=()
+while IFS= read -r _root; do
+  [[ -z "$_root" ]] || provision_roots+=("$_root")
+done < <(read_provision_config "${CONFIG_YML}")
+
+# ---------------------------------------------------------------------------
+# Provision each root
+# ---------------------------------------------------------------------------
+for root in "${provision_roots[@]:-}"; do
+  [[ -z "$root" ]] && continue
+
+  src="${REPO_ROOT}/${root}"
+  dst="${WORKTREE_ABS}/${root}"
+
+  # No-op if source does not exist at repo root.
+  if [[ ! -e "${src}" ]]; then
+    echo "[INFO] provision_worktree_config: source '${root}' absent at repo root — skipping"
+    continue
+  fi
+
+  # Idempotent: skip if already provisioned in the worktree.
+  if [[ -e "${dst}" || -L "${dst}" ]]; then
+    echo "[INFO] provision_worktree_config: '${root}' already present in worktree — skipping"
+    continue
+  fi
+
+  case "${PROVISION_MODE}" in
+    symlink)
+      # Symlink target MUST be absolute so the link resolves correctly
+      # from inside the worktree's nested directory depth (F5 absolute-path rule).
+      ln -s "${src}" "${dst}"
+      echo "[INFO] provision_worktree_config: symlinked '${dst}' -> '${src}'"
+      ;;
+    copy)
+      cp "${src}" "${dst}"
+      echo "[INFO] provision_worktree_config: copied '${src}' -> '${dst}'"
+      ;;
+  esac
+done
+
+exit 0