@sparkleideas/claude-flow-patch 3.1.0-alpha.44.patch.10

package/patch-all.sh

@@ -0,0 +1,199 @@
+#!/bin/bash
+# patch-all.sh — Orchestrator for folder-per-defect patches
+# Safe to run multiple times. Each fix.py is idempotent via patch()/patch_all().
+#
+# Usage:
+#   bash patch-all.sh [--global] [--target <dir>]
+#
+# Options:
+#   --global             Patch all global installs (npx cache + npm global)
+#   --target <dir>       Patch node_modules inside <dir>
+#
+# If neither flag is given, --global is assumed.
+
+set -euo pipefail
+
+# Parse arguments
+DO_GLOBAL=0
+TARGET_DIR=""
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --global)
+      DO_GLOBAL=1
+      shift
+      ;;
+    --target)
+      TARGET_DIR="${2:-}"
+      if [[ -z "$TARGET_DIR" ]]; then
+        echo "Error: --target requires a directory argument"
+        exit 1
+      fi
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: patch-all.sh [--global] [--target <dir>]"
+      echo ""
+      echo "Options:"
+      echo "  --global           Patch all global installs (npx cache + npm global)"
+      echo "  --target <dir>     Patch node_modules inside <dir>"
+      echo ""
+      echo "If neither flag is given, --global is assumed."
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Default: --global when nothing specified
+if [[ $DO_GLOBAL -eq 0 && -z "$TARGET_DIR" ]]; then
+  DO_GLOBAL=1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ── Shared discovery ──
+. "$SCRIPT_DIR/lib/discover.sh"
+
+# ── Collect installs ──
+# Each entry: "SCOPE\tdist_src\tversion\truvector_cli\truv_swarm_root\twritable"
+
+INSTALLS=()
+
+if [[ $DO_GLOBAL -eq 1 ]]; then
+  while IFS= read -r line; do
+    [ -n "$line" ] && INSTALLS+=("GLOBAL	$line")
+  done < <(discover_all_cf_installs)
+fi
+
+if [[ -n "$TARGET_DIR" ]]; then
+  if [[ ! -d "$TARGET_DIR" ]]; then
+    echo "Error: target directory does not exist: $TARGET_DIR"
+    exit 1
+  fi
+  TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+  while IFS= read -r line; do
+    [ -n "$line" ] && INSTALLS+=("TARGET	$line")
+  done < <(discover_target_installs "$TARGET_DIR")
+fi
+
+# ── Report what we found ──
+
+TARGETS=()
+if [[ $DO_GLOBAL -eq 1 ]]; then TARGETS+=(global); fi
+if [[ -n "$TARGET_DIR" ]]; then TARGETS+=("$TARGET_DIR"); fi
+echo "[PATCHES] Targets: ${TARGETS[*]}"
+echo ""
+
+if [[ ${#INSTALLS[@]} -eq 0 ]]; then
+  if [[ $DO_GLOBAL -eq 1 ]]; then
+    echo "  Global @claude-flow/cli: not found"
+    echo "  Global ruvector: not found"
+  fi
+  if [[ -n "$TARGET_DIR" ]]; then
+    echo "  Target @claude-flow/cli: not found in $TARGET_DIR"
+    echo "  Target ruvector: not found in $TARGET_DIR"
+  fi
+  echo ""
+  echo "[PATCHES] Complete"
+  exit 0
+fi
+
+for entry in "${INSTALLS[@]}"; do
+  IFS=$'\t' read -r scope dist_src version rv_cli rs_root writable <<< "$entry"
+  # "-" is the placeholder for empty fields (bash IFS collapses consecutive tabs)
+  [ "$rv_cli" = "-" ] && rv_cli=""
+  [ "$rs_root" = "-" ] && rs_root=""
+  echo "  [$scope] @claude-flow/cli v$version at $dist_src"
+  [ -n "$rv_cli" ] && echo "  [$scope] ruvector: $rv_cli"
+  [ -n "$rs_root" ] && echo "  [$scope] ruv-swarm: $rs_root"
+  if [ "$writable" = "no" ]; then
+    echo "  [$scope] WARNING: not writable (re-run with sudo)"
+  fi
+done
+
+echo ""
+
+# ── Apply patches function ──
+
+apply_patches() {
+  local base="$1"
+  local ruvector_cli="$2"
+  local ruv_swarm_root="$3"
+  local label="$4"
+
+  if [ -z "$base" ] && [ -z "$ruvector_cli" ]; then
+    echo "[$label] No packages found, skipping"
+    return
+  fi
+
+  if [ -n "$base" ]; then
+    echo "[$label] Patching @claude-flow/cli at: $base"
+  fi
+  if [ -n "$ruvector_cli" ]; then
+    echo "[$label] Patching ruvector at: $ruvector_cli"
+  fi
+
+  export BASE="${base:-/dev/null}"
+  export RUVECTOR_CLI="$ruvector_cli"
+  export RUV_SWARM_ROOT="$ruv_swarm_root"
+
+  # Dynamic discovery: concatenate common.py + all fix.py files sorted alphabetically.
+  # Alphabetical order preserves dependencies (e.g. NS-001 < NS-002 < NS-003).
+  #
+  # PATCH_INCLUDE / PATCH_EXCLUDE env vars filter by directory name regex.
+  python3 <(
+    cat "$SCRIPT_DIR/lib/common.py"
+
+    for fix in "$SCRIPT_DIR"/patch/*/fix.py; do
+      [ -f "$fix" ] || continue
+      dirname=$(basename "$(dirname "$fix")")
+      matchname="${dirname#[0-9][0-9][0-9]-}"   # strip NNN- prefix for pattern matching
+      if [ -n "${PATCH_INCLUDE:-}" ] && ! echo "$matchname" | grep -qE "$PATCH_INCLUDE"; then
+        continue
+      fi
+      if [ -n "${PATCH_EXCLUDE:-}" ] && echo "$matchname" | grep -qE "$PATCH_EXCLUDE"; then
+        continue
+      fi
+      cat "$fix"
+    done
+
+    echo "print(f\"[$label] Done: {applied} applied, {skipped} already present\")"
+  )
+
+  # Shell-based patches (e.g. EM-002: transformers cache permissions)
+  for fix in "$SCRIPT_DIR"/patch/*/fix.sh; do
+    [ -f "$fix" ] || continue
+    dirname=$(basename "$(dirname "$fix")")
+    matchname="${dirname#[0-9][0-9][0-9]-}"   # strip NNN- prefix for pattern matching
+    if [ -n "${PATCH_INCLUDE:-}" ] && ! echo "$matchname" | grep -qE "$PATCH_INCLUDE"; then
+      continue
+    fi
+    if [ -n "${PATCH_EXCLUDE:-}" ] && echo "$matchname" | grep -qE "$PATCH_EXCLUDE"; then
+      continue
+    fi
+    bash "$fix" 2>/dev/null || true
+  done
+
+  echo ""
+}
+
+# ── Apply to each discovered install ──
+
+for entry in "${INSTALLS[@]}"; do
+  IFS=$'\t' read -r scope dist_src version rv_cli rs_root writable <<< "$entry"
+  [ "$rv_cli" = "-" ] && rv_cli=""
+  [ "$rs_root" = "-" ] && rs_root=""
+
+  if [ "$writable" = "no" ]; then
+    echo "[$scope] SKIP: $dist_src not writable (re-run with sudo)"
+    echo ""
+    continue
+  fi
+
+  apply_patches "$dist_src" "$rv_cli" "$rs_root" "$scope"
+done
+
+echo "[PATCHES] Complete"

package/repair-post-init.sh

@@ -0,0 +1,263 @@
+#!/bin/bash
+# repair-post-init.sh
+# Post-init remediation for projects initialized before patch-all.sh.
+#
+# What it does:
+# 1) Finds a patched @claude-flow/cli helper source (local or global npx cache)
+# 2) Backs up target .claude/helpers (default)
+# 3) Rehydrates helper files into target project
+# 4) Preserves/installs a guidance-aware hook-handler when available
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET_DIR="$(pwd)"
+SOURCE_SCOPE="auto"   # auto|local|global
+DO_BACKUP=1
+DRY_RUN=0
+RUN_CHECK=1
+
+usage() {
+  cat <<'EOF'
+Usage:
+  bash repair-post-init.sh [options]
+
+Options:
+  --target <dir>        Target project directory (default: current working directory)
+  --source <mode>       Source mode: auto|local|global (default: auto)
+  --no-backup           Skip .claude/helpers backup
+  --dry-run             Print actions without writing files
+  --skip-check          Skip check-patches.sh preflight
+  -h, --help            Show help
+
+Examples:
+  bash repair-post-init.sh --target ~/src/my-project
+  bash repair-post-init.sh --target ~/src/my-project --source global
+  bash repair-post-init.sh --target ~/src/my-project --dry-run
+EOF
+}
+
+fail() {
+  echo "[repair-post-init] ERROR: $*" >&2
+  exit 1
+}
+
+log() {
+  echo "[repair-post-init] $*"
+}
+
+run_cmd() {
+  if [ "$DRY_RUN" -eq 1 ]; then
+    echo "[dry-run] $*"
+    return 0
+  fi
+  "$@"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)
+      TARGET_DIR="${2:-}"
+      shift 2
+      ;;
+    --source)
+      SOURCE_SCOPE="${2:-}"
+      shift 2
+      ;;
+    --no-backup)
+      DO_BACKUP=0
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --skip-check)
+      RUN_CHECK=0
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "Unknown option: $1"
+      ;;
+  esac
+done
+
+if [[ ! "$SOURCE_SCOPE" =~ ^(auto|local|global)$ ]]; then
+  fail "Invalid --source value: $SOURCE_SCOPE (expected auto|local|global)"
+fi
+
+TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+[ -d "$TARGET_DIR" ] || fail "Target directory not found: $TARGET_DIR"
+
+if [ "$RUN_CHECK" -eq 1 ]; then
+  if [ -x "$SCRIPT_DIR/check-patches.sh" ]; then
+    log "Running preflight patch check..."
+    bash "$SCRIPT_DIR/check-patches.sh" >/dev/null || {
+      log "Patch check failed; applying patches..."
+      bash "$SCRIPT_DIR/patch-all.sh" --global >/dev/null
+      bash "$SCRIPT_DIR/check-patches.sh" >/dev/null || fail "Patch verification failed"
+    }
+  else
+    log "check-patches.sh not found; skipping preflight"
+  fi
+fi
+
+find_local_helpers() {
+  local base="$1"
+  for d in "$base" "$base/.." "$base/../.." "$base/../../.."; do
+    if [ -d "$d/node_modules/@claude-flow/cli/.claude/helpers" ]; then
+      (cd "$d/node_modules/@claude-flow/cli/.claude/helpers" && pwd)
+      return 0
+    fi
+  done
+  return 1
+}
+
+find_global_helpers() {
+  # Use shared discovery to find all installs, then derive helpers path
+  . "$SCRIPT_DIR/lib/discover.sh"
+  local first_dist_src=""
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    first_dist_src="${line%%	*}"
+    break
+  done < <(discover_all_cf_installs)
+  if [ -n "$first_dist_src" ]; then
+    # dist/src -> package root -> .claude/helpers
+    local pkg_root
+    pkg_root="$(cd "$first_dist_src/../.." 2>/dev/null && pwd)"
+    if [ -d "$pkg_root/.claude/helpers" ]; then
+      echo "$pkg_root/.claude/helpers"
+      return 0
+    fi
+  fi
+  # Fallback: legacy direct glob
+  ls -td ~/.npm/_npx/*/node_modules/@claude-flow/cli/.claude/helpers 2>/dev/null | head -1 || true
+}
+
+SRC_HELPERS=""
+case "$SOURCE_SCOPE" in
+  local)
+    SRC_HELPERS="$(find_local_helpers "$TARGET_DIR" || true)"
+    ;;
+  global)
+    SRC_HELPERS="$(find_global_helpers)"
+    ;;
+  auto)
+    SRC_HELPERS="$(find_local_helpers "$TARGET_DIR" || true)"
+    if [ -z "$SRC_HELPERS" ]; then
+      SRC_HELPERS="$(find_global_helpers)"
+    fi
+    ;;
+esac
+
+[ -n "$SRC_HELPERS" ] || fail "Could not locate @claude-flow/cli/.claude/helpers (source=$SOURCE_SCOPE)"
+[ -d "$SRC_HELPERS" ] || fail "Source helpers directory does not exist: $SRC_HELPERS"
+[ -f "$SRC_HELPERS/intelligence.cjs" ] || fail "Source missing intelligence.cjs: $SRC_HELPERS"
+
+TARGET_HELPERS="$TARGET_DIR/.claude/helpers"
+BACKUP_PATH="$TARGET_DIR/.claude/helpers.backup.$(date +%Y%m%d-%H%M%S)"
+
+log "Target: $TARGET_DIR"
+log "Source helpers: $SRC_HELPERS"
+log "Target helpers: $TARGET_HELPERS"
+
+run_cmd mkdir -p "$TARGET_HELPERS"
+
+if [ "$DO_BACKUP" -eq 1 ] && [ -d "$TARGET_HELPERS" ]; then
+  if [ "$(ls -A "$TARGET_HELPERS" 2>/dev/null || true)" ]; then
+    log "Backing up existing helpers -> $BACKUP_PATH"
+    run_cmd cp -a "$TARGET_HELPERS" "$BACKUP_PATH"
+  fi
+fi
+
+# Copy all helpers except hook-handler.cjs first.
+copied=0
+for src in "$SRC_HELPERS"/*; do
+  [ -e "$src" ] || continue
+  base="$(basename "$src")"
+  if [ "$base" = "hook-handler.cjs" ]; then
+    continue
+  fi
+  run_cmd cp -a "$src" "$TARGET_HELPERS/$base"
+  copied=$((copied + 1))
+done
+
+# Prefer guidance-aware hook-handler when installed in target project.
+GUIDANCE_HANDLER="$TARGET_DIR/node_modules/claude-flow-guidance-implementation/scaffold/.claude/helpers/hook-handler.cjs"
+HOOK_SRC="$SRC_HELPERS/hook-handler.cjs"
+HOOK_REASON="@claude-flow/cli helper template"
+if [ -f "$GUIDANCE_HANDLER" ]; then
+  HOOK_SRC="$GUIDANCE_HANDLER"
+  HOOK_REASON="guidance implementation hook-handler"
+fi
+
+if [ -f "$HOOK_SRC" ]; then
+  log "Installing hook-handler from: $HOOK_REASON"
+  run_cmd cp -a "$HOOK_SRC" "$TARGET_HELPERS/hook-handler.cjs"
+  copied=$((copied + 1))
+fi
+
+# Make guidance hook-handler path resolution work when copied into project .claude/helpers.
+if [ "$DRY_RUN" -eq 0 ] && [ -f "$TARGET_HELPERS/hook-handler.cjs" ]; then
+  python3 - "$TARGET_HELPERS/hook-handler.cjs" <<'PY'
+import pathlib
+import sys
+
+path = pathlib.Path(sys.argv[1])
+text = path.read_text()
+
+start = text.find("function getBundledScriptPath(scriptName)")
+end = text.find("function getGuidanceScriptPath()", start if start >= 0 else 0)
+
+if start >= 0 and end > start and "claude-flow-guidance-implementation" not in text:
+    replacement = """function getBundledScriptPath(scriptName) {
+  return path.join(
+    getProjectDir(),
+    'node_modules',
+    'claude-flow-guidance-implementation',
+    'scaffold',
+    'scripts',
+    scriptName
+  );
+}
+
+function resolveGuidanceScriptPath(scriptName) {
+  const localPath = path.join(getProjectDir(), 'scripts', scriptName);
+  if (fs.existsSync(localPath)) return localPath;
+
+  const bundledPath = getBundledScriptPath(scriptName);
+  if (fs.existsSync(bundledPath)) return bundledPath;
+
+  // Keep compatibility for handler copies that live under scaffold/.claude/helpers.
+  const relativeBundledPath = path.resolve(__dirname, '..', '..', 'scripts', scriptName);
+  if (fs.existsSync(relativeBundledPath)) return relativeBundledPath;
+
+  return localPath;
+}
+
+"""
+    text = text[:start] + replacement + text[end:]
+    path.write_text(text)
+PY
+fi
+
+if [ "$DRY_RUN" -eq 0 ] && [ -f "$TARGET_HELPERS/hook-handler.cjs" ]; then
+  chmod +x "$TARGET_HELPERS/hook-handler.cjs" || true
+fi
+
+log "Copied/updated helper files: $copied"
+
+if [ "$DRY_RUN" -eq 0 ] && [ -f "$TARGET_HELPERS/hook-handler.cjs" ]; then
+  if node "$TARGET_HELPERS/hook-handler.cjs" status >/dev/null 2>&1; then
+    log "Smoke check: hook-handler status OK"
+  else
+    log "WARN: hook-handler status returned non-zero"
+  fi
+fi
+
+log "Done."

package/scripts/preflight.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+// scripts/preflight.mjs — Pre-commit/pre-publish consistency check.
+// Syncs: doc tables, defect counts, version strings across all files.
+// Source of truth: package.json (version), npm/config.json (targets), patch/*/ (defects).
+//
+// Usage: node scripts/preflight.mjs [--check]
+//   --check  Exit 1 if anything is out of date (for hooks/CI), don't write.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { discover } from '../lib/discover.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const checkOnly = process.argv.includes('--check');
+
+const data = discover();
+const { patches, categories, stats } = data;
+
+// ── Sources of truth ──
+
+const pkgJson = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8'));
+const configJson = JSON.parse(readFileSync(resolve(ROOT, 'npm', 'config.json'), 'utf-8'));
+const pkgVersion = pkgJson.version;
+const cliTarget = configJson.targets['@claude-flow/cli'];
+const swarmTarget = configJson.targets['ruv-swarm'];
+
+// ── Helpers ──
+
+/** Group patches by prefix, preserving sort order. */
+function groupByPrefix(patches) {
+  const groups = new Map();
+  for (const p of patches) {
+    if (!groups.has(p.prefix)) groups.set(p.prefix, []);
+    groups.get(p.prefix).push(p);
+  }
+  return groups;
+}
+
+/**
+ * Replace content between marker comments in a file.
+ * Returns true if content changed.
+ */
+function replaceMarkerSection(filePath, markerName, newContent) {
+  const beginMarker = `<!-- GENERATED:${markerName}:begin -->`;
+  const endMarker = `<!-- GENERATED:${markerName}:end -->`;
+
+  const text = readFileSync(filePath, 'utf-8');
+  const beginIdx = text.indexOf(beginMarker);
+  const endIdx = text.indexOf(endMarker);
+
+  if (beginIdx < 0 || endIdx < 0) {
+    console.error(`ERROR: Markers ${beginMarker} / ${endMarker} not found in ${filePath}`);
+    console.error('  Add them around the section that should be auto-generated.');
+    process.exit(1);
+  }
+
+  const before = text.slice(0, beginIdx + beginMarker.length);
+  const after = text.slice(endIdx);
+  const updated = `${before}\n${newContent}\n${after}`;
+
+  if (updated === text) return false;
+
+  if (!checkOnly) writeFileSync(filePath, updated);
+  return true;
+}
+
+/**
+ * Replace all occurrences of a version string in a file.
+ * Returns true if content changed.
+ */
+function syncVersionInFile(filePath, oldVersion, newVersion, label) {
+  if (oldVersion === newVersion) return false;
+  const text = readFileSync(filePath, 'utf-8');
+  if (!text.includes(oldVersion)) return false;
+  const updated = text.replaceAll(oldVersion, newVersion);
+  if (updated === text) return false;
+  if (!checkOnly) writeFileSync(filePath, updated);
+  return true;
+}
+
+// ── Generate README.md defect index ──
+
+function generateReadmeIndex() {
+  const groups = groupByPrefix(patches);
+  const lines = [`${stats.total} defects across ${stats.categories} categories.`];
+
+  for (const [prefix, items] of groups) {
+    const catLabel = categories[prefix] ?? prefix;
+    lines.push('');
+    lines.push(`### ${prefix} -- ${catLabel}`);
+    lines.push('');
+    lines.push('| ID | Description <img width="500" height="1" /> | Severity | GitHub&nbsp;Issue |');
+    lines.push('|----|-------------|----------|--------------|');
+
+    for (const p of items) {
+      const idLink = `[${p.id.replace('-', '&#8209;')}](patch/${p.dir}/)`;
+      const ghLink = p.githubUrl ? `[${p.github}](${p.githubUrl})` : p.github;
+      lines.push(`| ${idLink} | ${p.title} | ${p.severity} | ${ghLink} |`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ── Generate CLAUDE.md defect tables ──
+
+function generateClaudeTables() {
+  const groups = groupByPrefix(patches);
+  const lines = [];
+
+  // Category summary table
+  lines.push('| Prefix | Category | Count |');
+  lines.push('|--------|----------|-------|');
+  for (const [prefix, items] of groups) {
+    const catLabel = categories[prefix] ?? prefix;
+    lines.push(`| ${prefix} | ${catLabel} | ${items.length} |`);
+  }
+
+  // Full defect list
+  lines.push('');
+  lines.push(`## All ${stats.total} Defects`);
+  lines.push('');
+  lines.push('| ID | GitHub Issue | Severity |');
+  lines.push('|----|-------------|----------|');
+  for (const p of patches) {
+    const ghText = p.github ? `${p.github} ${p.title}` : p.title;
+    const ghLink = p.githubUrl ? `[${ghText}](${p.githubUrl})` : ghText;
+    lines.push(`| ${p.id} | ${ghLink} | ${p.severity} |`);
+  }
+
+  return lines.join('\n');
+}
+
+// ── Generate npm/README.md defect list ──
+
+const REPO_URL = 'https://github.com/sparkling/claude-flow-patch';
+
+function generateNpmDefectList() {
+  const groups = groupByPrefix(patches);
+  const lines = [
+    `${stats.total} tracked defects across ${stats.categories} categories.`,
+    '',
+    '| Defect | Description | GitHub Issue |',
+    '|--------|-------------|-------------|',
+  ];
+
+  for (const [, items] of groups) {
+    for (const p of items) {
+      const defectLink = `[${p.id}](${REPO_URL}/tree/master/patch/${p.dir})`;
+      const ghLink = p.githubUrl ? `[${p.github}](${p.githubUrl})` : p.github;
+      lines.push(`| ${defectLink} | ${p.title} | ${ghLink} |`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function updateNpmReadme() {
+  return replaceMarkerSection(
+    resolve(ROOT, 'npm', 'README.md'),
+    'npm-defects',
+    generateNpmDefectList()
+  );
+}
+
+// ── Sync npm/config.json (version + defect counts) ──
+
+function updateNpmConfig() {
+  const filePath = resolve(ROOT, 'npm', 'config.json');
+  const config = JSON.parse(readFileSync(filePath, 'utf-8'));
+
+  let changed = false;
+
+  // Sync version.current from package.json
+  if (config.version?.current !== pkgVersion) {
+    config.version.current = pkgVersion;
+    changed = true;
+  }
+
+  // Sync defect counts from discovery
+  if (config.defects?.total !== stats.total) {
+    config.defects.total = stats.total;
+    changed = true;
+  }
+  if (config.defects?.categories !== stats.categories) {
+    config.defects.categories = stats.categories;
+    changed = true;
+  }
+
+  if (changed && !checkOnly) {
+    writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+  }
+  return changed;
+}
+
+// ── Main ──
+
+let anyChanged = false;
+
+function report(changed, label) {
+  if (!changed) return;
+  anyChanged = true;
+  console.log(checkOnly ? `STALE: ${label}` : `Updated: ${label}`);
+}
+
+// 1. Doc tables (marker-based sections)
+report(
+  replaceMarkerSection(resolve(ROOT, 'README.md'), 'defect-index', generateReadmeIndex()),
+  'README.md (defect index)'
+);
+report(
+  replaceMarkerSection(resolve(ROOT, 'CLAUDE.md'), 'defect-tables', generateClaudeTables()),
+  'CLAUDE.md (defect tables)'
+);
+report(updateNpmReadme(), 'npm/README.md (defect list)');
+
+// 2. Config sync (version + counts)
+report(updateNpmConfig(), 'npm/config.json (version/counts)');
+
+// 3. Upstream baseline version in prose (sync from npm/config.json targets)
+// Find any stale version strings and replace with current targets.
+// We scan for the pattern v?X.Y.Z-alpha.N and replace if it doesn't match config.
+const versionFiles = ['README.md', 'CLAUDE.md', 'npm/README.md', 'AGENTS.md'];
+for (const file of versionFiles) {
+  const filePath = resolve(ROOT, file);
+  let text;
+  try { text = readFileSync(filePath, 'utf-8'); } catch { continue; }
+
+  let updated = text;
+
+  // Sync @claude-flow/cli version references
+  // Match patterns like **v3.1.0-alpha.NN** or `3.1.0-alpha.NN` or @3.1.0-alpha.NN
+  const cliRe = /(?<=[@`*v])3\.1\.0-alpha\.\d+/g;
+  updated = updated.replace(cliRe, cliTarget);
+
+  if (updated !== text) {
+    if (!checkOnly) writeFileSync(filePath, updated);
+    report(true, `${file} (upstream baseline)`);
+  }
+}
+
+if (!anyChanged) {
+  console.log('All files are up to date.');
+} else if (checkOnly) {
+  console.log('\nFiles are out of date. Run: npm run preflight');
+  process.exit(1);
+}