@xulthekl/team-flow 0.22.4

package/scripts/lib/cmd-state.mjs

@@ -0,0 +1,231 @@
+// scripts/lib/cmd-state.mjs — tf state subcommand handler
+import { parseArgs } from 'node:util';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readState, writeState, updateField, rebuildState } from './state-loader.mjs';
+import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const VALID_STATES = [
+  'exploring', 'specifying', 'bridging', 'approved-for-build',
+  'executing', 'debugging', 'closing', 'abandoned',
+];
+
+const SETTABLE_FIELDS = [
+  'workflow', 'test_result', 'batches_completed', 'spec_merged',
+  'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
+  'dp_1_result', 'dp_1_timestamp', 'dp_1_decisions', 'dp_1_confirmed',
+  'dp_2_result', 'dp_2_timestamp', 'dp_2_decisions', 'dp_2_confirmed',
+  'dp_3_result', 'dp_3_timestamp', 'dp_3_decisions', 'dp_3_confirmed',
+  'dp_5_result', 'dp_5_timestamp', 'dp_5_decisions', 'dp_5_confirmed',
+  'dp_6_result', 'dp_6_timestamp', 'dp_6_decisions', 'dp_6_confirmed',
+  'dp_7_result', 'dp_7_timestamp', 'dp_7_decisions', 'dp_7_confirmed',
+];
+
+export async function run(args) {
+  const { positionals, values } = parseArgs({
+    args,
+    options: {
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const sub = positionals[0];  // init | check | transition | get | rebuild | set
+  const changeDir = positionals[1];
+  const arg = positionals[2];  // <to-state> for transition, <field> for get
+
+  if (!changeDir) {
+    console.error('Usage: tf state <subcommand> <change-dir> [arg]');
+    console.error('Subcommands: init, check, transition, get, rebuild, set');
+    process.exit(2);
+  }
+
+  // Unknown subcommand: report a usage error (exit 2) BEFORE the BUG-B
+  // state-file existence check, so a bad subcommand is not masked by the
+  // "No state file" error (which would return exit 1 instead of exit 2).
+  const KNOWN_SUBS = ['init', 'check', 'transition', 'get', 'rebuild', 'set'];
+  if (!KNOWN_SUBS.includes(sub)) {
+    console.error(`Unknown subcommand: ${sub}. Valid: ${KNOWN_SUBS.join(', ')}`);
+    process.exit(2);
+  }
+
+  // BUG-B: every subcommand except `init` requires an existing state file.
+  // Without this check, readState silently returns defaults and `set` would
+  // create a phantom .team-flow.yaml in the wrong directory (state drift).
+  if (sub !== 'init') {
+    const STATE_FILE = '.team-flow.yaml';
+    if (!existsSync(join(changeDir, STATE_FILE))) {
+      console.error(`No state file at ${join(changeDir, STATE_FILE)}. Run 'tf state init <change-dir>' first.`);
+      process.exit(1);
+    }
+  }
+
+  switch (sub) {
+    case 'init': {
+      if (!existsSync(changeDir)) {
+        mkdirSync(changeDir, { recursive: true });
+      }
+      const hash = computeArtifactsHash(changeDir);
+      const ch = computeContractHash(changeDir);
+      const state = readState(changeDir);
+      state.artifacts_hash = hash;
+      state.contract_hash = ch;
+      state.last_transition = new Date().toISOString();
+      writeState(changeDir, state);
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch }));
+      } else {
+        console.log(`State initialized. artifacts_hash: ${hash}`);
+      }
+      break;
+    }
+    case 'check': {
+      const state = readState(changeDir);
+      const currentHash = computeArtifactsHash(changeDir);
+      const consistent = state.artifacts_hash === currentHash;
+      if (values.json) {
+        console.log(JSON.stringify({
+          consistent,
+          stored_hash: state.artifacts_hash,
+          current_hash: currentHash,
+          state: state.state,
+        }));
+      } else {
+        if (consistent) {
+          console.log('State consistent with artifacts.');
+        } else {
+          console.log('State INCONSISTENT — artifacts have changed since last transition.');
+        }
+        console.log(`  State: ${state.state}, stored hash: ${state.artifacts_hash}`);
+        console.log(`  Current hash: ${currentHash}`);
+      }
+      process.exit(consistent ? 0 : 1);
+      break;
+    }
+    case 'transition': {
+      const toState = arg;
+      if (!toState) {
+        console.error('Usage: tf state transition <change-dir> <to-state>');
+        process.exit(2);
+      }
+
+      // Validate state name
+      if (!VALID_STATES.includes(toState)) {
+        console.error(`Invalid state: '${toState}'. Must be one of: ${VALID_STATES.join(', ')}`);
+        process.exit(1);
+      }
+
+      const state = readState(changeDir);
+      const fromState = state.state;
+
+      // Run guard before allowing transition (H-2: enforce guard)
+      const guardScript = join(__dirname, '..', 'guard', 'guard.mjs');
+      const rawWorkflow = state.workflow || 'full';
+      // Normalize: guard only accepts full/hotfix/tweak, not "auto"
+      const workflow = rawWorkflow === 'auto' ? 'full' : rawWorkflow;
+      const guardResult = spawnSync('node', [guardScript, 'check', changeDir, fromState, toState, '--json', '--workflow', workflow], {
+        cwd: join(__dirname, '..', '..'),
+        timeout: 10_000,
+      });
+
+      const guardOutput = guardResult.stdout?.toString() ?? '';
+      const guardStderr = guardResult.stderr?.toString().trim() ?? '';
+      if (guardResult.error) {
+        console.error(`Guard check failed for ${fromState} -> ${toState}:`);
+        console.error(`  [guard-error] ${guardResult.error.message}`);
+        if (guardStderr) console.error(`  ${guardStderr}`);
+        process.exit(1);
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(guardOutput);
+      } catch {
+        console.error(`Guard check failed for ${fromState} -> ${toState}:`);
+        console.error('  [guard-error] Guard did not return valid JSON.');
+        if (guardStderr) console.error(`  ${guardStderr}`);
+        process.exit(1);
+      }
+
+      if (guardResult.status !== 0 || parsed.pass !== true) {
+        const failures = (parsed.checks || [])
+          .filter(c => !c.pass)
+          .flatMap(c => (c.failures || []).map(f => `[${c.dimension}] ${f}`));
+        console.error(`Guard check failed for ${fromState} -> ${toState}:`);
+        for (const f of failures) console.error(`  ${f}`);
+        if (parsed.error) console.error(`  ${parsed.error}`);
+        if (failures.length === 0 && !parsed.error) {
+          console.error('  [guard-error] Guard failed without a structured failure message.');
+        }
+        process.exit(1);
+      }
+
+      state.state = toState;
+      state.last_transition_from = fromState;
+      state.last_transition_to = toState;
+      state.last_transition = new Date().toISOString();
+      writeState(changeDir, state);
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, from: fromState, to: toState }));
+      } else {
+        console.log(`State transitioned: ${fromState} -> ${toState}`);
+      }
+      break;
+    }
+    case 'get': {
+      const field = arg;
+      if (!field) {
+        console.error('Usage: tf state get <change-dir> <field>');
+        process.exit(2);
+      }
+      const state = readState(changeDir);
+      if (!Object.prototype.hasOwnProperty.call(state, field) && field in state) {
+        console.error(`Field '${field}' is not a valid state field`);
+        process.exit(1);
+      }
+      const value = state[field];
+      if (values.json) {
+        console.log(JSON.stringify({ field, value: value ?? null }));
+      } else {
+        console.log(value ?? 'null');
+      }
+      break;
+    }
+    case 'rebuild': {
+      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash });
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, state: state.state }));
+      } else {
+        console.log(`State rebuilt from artifacts. state: ${state.state}`);
+      }
+      break;
+    }
+    case 'set': {
+      // tf state set <change-dir> <field> <value>
+      const field = arg;
+      const value = positionals[3];
+      if (!field || value === undefined) {
+        console.error('Usage: tf state set <change-dir> <field> <value>');
+        process.exit(2);
+      }
+      if (!SETTABLE_FIELDS.includes(field)) {
+        console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
+        process.exit(1);
+      }
+      updateField(changeDir, field, value);
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, field, value }));
+      } else {
+        console.log(`✅ Set ${field} = ${value}`);
+      }
+      break;
+    }
+    default:
+      console.error(`Unknown subcommand: ${sub}. Valid: init, check, transition, get, rebuild, set`);
+      process.exit(2);
+  }
+}

package/scripts/lib/cmd-sync.mjs

@@ -0,0 +1,102 @@
+// tf sync <change-dir> — merge delta specs into main specs with conflict detection
+import { readFileSync, readdirSync, writeFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
+import path, { join, basename } from 'node:path';
+import { validateSpecPathLayout } from './spec-paths.mjs';
+
+function toPosix(value) {
+  return value.replace(/\\/g, '/');
+}
+
+function pathApiFor(...values) {
+  return values.some(value => value.includes('\\')) ? path.win32 : path.posix;
+}
+
+export function deriveCapabilityDir(changeSpecsDir, specFile) {
+  const api = pathApiFor(changeSpecsDir, specFile);
+  const relative = toPosix(api.relative(changeSpecsDir, specFile));
+  return relative.replace(/\/spec\.md$/, '');
+}
+
+export async function run(args) {
+  if (args.length < 1) {
+    console.error('Usage: tf sync <change-dir>');
+    process.exit(2);
+  }
+
+  const changeDir = args[0];
+  if (!existsSync(changeDir)) {
+    console.error(`Error: "${changeDir}" not found`);
+    process.exit(2);
+  }
+
+  const { Validator } = await import('../../dist/index.js');
+  const validator = new Validator();
+
+  // Collect all unsynced changes for conflict detection
+  const changesDir = join(process.cwd(), 'changes');
+  const allDeltas = [];
+
+  if (existsSync(changesDir)) {
+    for (const dir of readdirSync(changesDir)) {
+      const dirPath = join(changesDir, dir);
+      if (!statSync(dirPath).isDirectory()) continue;
+      const layout = validateSpecPathLayout(dirPath, { requireSpecs: false });
+      if (!layout.pass) {
+        for (const failure of layout.failures) console.error(failure);
+        process.exit(1);
+      }
+      if (layout.specFiles.length === 0) continue;
+
+      for (const specFile of layout.specFiles) {
+        const content = readFileSync(specFile, 'utf-8');
+        allDeltas.push({ changeName: dir, content });
+      }
+    }
+  }
+
+  // Check for conflicts
+  if (allDeltas.length > 0) {
+    const conflictReport = validator.detectSyncConflicts(allDeltas);
+    if (conflictReport.hasConflicts) {
+      console.log('⚠️  Sync conflicts detected:\n');
+      for (const conflict of conflictReport.conflicts) {
+        console.log(`  Requirement: "${conflict.requirement}"`);
+        console.log(`  Modified by: ${conflict.changes.join(', ')}\n`);
+      }
+      console.log('Resolve conflicts before syncing. Consider syncing changes one at a time.');
+      process.exit(1);
+    }
+  }
+
+  // Perform sync: copy delta specs to main specs/
+  const changeSpecsDir = join(changeDir, 'specs');
+  const mainSpecsDir = join(process.cwd(), 'specs');
+  const changeName = basename(changeDir);
+  const layout = validateSpecPathLayout(changeDir, { requireSpecs: true });
+  if (!layout.pass) {
+    for (const failure of layout.failures) console.error(failure);
+    process.exit(1);
+  }
+
+  if (!existsSync(mainSpecsDir)) {
+    mkdirSync(mainSpecsDir, { recursive: true });
+  }
+
+  let synced = 0;
+
+  for (const specFile of layout.specFiles) {
+    const capabilityDir = deriveCapabilityDir(changeSpecsDir, specFile);
+    const targetDir = join(mainSpecsDir, capabilityDir);
+
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    const content = readFileSync(specFile, 'utf-8');
+    writeFileSync(join(targetDir, 'spec.md'), content);
+    console.log(`  📋 Synced: specs/${capabilityDir}/spec.md`);
+    synced++;
+  }
+
+  console.log(`\n✅ Synced ${synced} spec(s) from ${changeName} to specs/`);
+}

package/scripts/lib/cmd-validate.mjs

@@ -0,0 +1,105 @@
+// tf validate <dir> — validate artifacts in a change directory
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { loadConfig } from './config-loader.mjs';
+import { validateSpecPathLayout, relativeSpecPath } from './spec-paths.mjs';
+
+async function getValidator() {
+  const mod = await import('../../dist/index.js');
+  return new mod.Validator(false);
+}
+
+function printReport(label, report) {
+  console.log(`\n  📋 ${label}`);
+  if (report.valid) {
+    console.log(`     ✅ valid (${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info)`);
+  } else {
+    console.log(`     ❌ invalid (${report.summary.errors} errors, ${report.summary.warnings} warnings, ${report.summary.info} info)`);
+  }
+  for (const issue of report.issues) {
+    const icon = issue.level === 'ERROR' ? '🔴' : issue.level === 'WARNING' ? '🟡' : '🔵';
+    console.log(`     ${icon} [${issue.level}] ${issue.path}: ${issue.message}`);
+  }
+}
+
+export async function run(args) {
+  if (args.length < 1) {
+    console.error('Usage: tf validate <change-dir>');
+    process.exit(2);
+  }
+
+  const changeDir = args[0];
+  if (!existsSync(changeDir) || !statSync(changeDir).isDirectory()) {
+    console.error(`Error: "${changeDir}" is not a valid directory`);
+    process.exit(2);
+  }
+
+  const config = loadConfig(process.cwd());
+  const changeName = basename(changeDir);
+  const validator = await getValidator();
+
+  console.log(`🔍 Validating: ${changeDir}`);
+  console.log(`   Change: ${changeName}`);
+
+  let hasErrors = false;
+
+  // Validate proposal.md
+  const proposalPath = join(changeDir, 'proposal.md');
+  if (existsSync(proposalPath)) {
+    const content = readFileSync(proposalPath, 'utf-8');
+    const report = validator.validateChangeContent(changeName, content);
+    printReport('proposal.md', report);
+    if (!report.valid) hasErrors = true;
+  }
+
+  // Validate specs/*/spec.md
+  const specLayout = validateSpecPathLayout(changeDir, { requireSpecs: true });
+  for (const failure of specLayout.failures) {
+    printReport('specs/', {
+      valid: false,
+      issues: [{ level: 'ERROR', path: 'specs/', message: failure }],
+      summary: { errors: 1, warnings: 0, info: 0 },
+    });
+    hasErrors = true;
+  }
+
+  for (const specFile of specLayout.specFiles) {
+    const content = readFileSync(specFile, 'utf-8');
+    const report = validator.validateDeltaSpec(content);
+    const rel = relativeSpecPath(changeDir, specFile);
+    printReport(rel, report);
+    if (!report.valid) hasErrors = true;
+  }
+
+  // Basic structural validation for design.md and tasks.md (shared pattern)
+  const STRUCTURAL_CHECKS = [
+    { file: 'design.md', errorMsg: 'design.md is too short (< 50 chars) — provide architecture decisions, trade-offs, and data flow', warningMsg: 'design.md has no section headings — consider adding ## Architecture, ## Data Flow, ## Error Handling' },
+    { file: 'tasks.md', errorMsg: 'tasks.md is too short (< 50 chars) — provide actionable, ordered implementation tasks', warningMsg: 'tasks.md has no section headings — consider adding ## File Structure and ## Tasks' },
+  ];
+
+  for (const { file, errorMsg, warningMsg } of STRUCTURAL_CHECKS) {
+    const filePath = join(changeDir, file);
+    if (!existsSync(filePath)) continue;
+
+    const content = readFileSync(filePath, 'utf-8').trim();
+    const issues = [];
+    if (content.length < 50) issues.push({ level: 'ERROR', path: file, message: errorMsg });
+    if (!content.includes('##')) issues.push({ level: 'WARNING', path: file, message: warningMsg });
+    const report = {
+      valid: issues.filter(i => i.level === 'ERROR').length === 0,
+      issues,
+      summary: { errors: issues.filter(i => i.level === 'ERROR').length, warnings: issues.filter(i => i.level === 'WARNING').length, info: 0 },
+    };
+    printReport(file, report);
+    if (!report.valid) hasErrors = true;
+  }
+
+  console.log('');
+  if (hasErrors) {
+    console.log('❌ Validation failed with errors.');
+    process.exit(1);
+  } else {
+    console.log('✅ All artifacts validated.');
+    process.exit(0);
+  }
+}

package/scripts/lib/cmd-version.mjs

@@ -0,0 +1,148 @@
+// tf version <semver> — sync version to all manifest and documentation files
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ── JSON manifests with structured path ──
+const MANIFESTS = [
+  { file: 'package.json', path: ['version'] },
+  { file: 'plugin.json', path: ['version'] },
+  { file: '.claude-plugin/plugin.json', path: ['version'] },
+  { file: '.claude-plugin/marketplace.json', path: ['plugins', '0', 'version'] },
+  { file: '.cursor-plugin/plugin.json', path: ['version'] },
+  { file: '.cursor-plugin/marketplace.json', path: ['metadata', 'version'] },
+  { file: '.codex-plugin/plugin.json', path: ['version'] },
+  { file: 'gemini-extension.json', path: ['version'] },
+  { file: '.github/plugin/marketplace.json', path: ['metadata', 'version'] },
+  { file: '.github/plugin/marketplace.json', path: ['plugins', '0', 'version'] },
+];
+
+// ── Text files with regex patterns (first capture group = version to replace) ──
+// Note: CLAUDE.md is intentionally gitignored (project-local AI instructions).
+const TEXT_FILES = [
+  { file: 'README.md',              pattern: /(当前版本：`v?)0\.\d+\.\d+(`?)/g,                   replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'INSTALL.md',             pattern: /(当前发布版本：\*\*v)0\.\d+\.\d+(\*\*)/g,            replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'docs/README_en.md',      pattern: /(Current: `v)0\.\d+\.\d+(`)/g,                     replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'hooks/session-start',    pattern: /(# v)0\.\d+\.\d+(: conditional injection)/g,       replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'llms.txt',               pattern: /(Current version: v)0\.\d+\.\d+(\.)/g,             replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: '.claude/always/phase-guard.md', pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,      replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'GEMINI.md',              pattern: /(# team-flow v)0\.\d+\.\d+( \|)/g,              replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/workflow-start/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/need-explorer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-writer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/contract-builder/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/implementer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/build-executor/task-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/code-reviewer/code-reviewer-prompt.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/bug-investigator/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/release-archivist/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+  { file: 'skills/spec-merger/SKILL.md', pattern: /(npx --yes --package @xulthekl\/team-flow@)0\.\d+\.\d+( tf)/g, replacement: '$10.%MINOR%.%PATCH%$2' },
+];
+
+function getNestedValue(obj, pathParts) {
+  let val = obj;
+  for (const p of pathParts) {
+    if (val === undefined || val === null) return undefined;
+    val = val[p];
+  }
+  return val;
+}
+
+function setNestedValue(obj, pathParts, value) {
+  let target = obj;
+  for (let i = 0; i < pathParts.length - 1; i++) {
+    target = target[pathParts[i]];
+  }
+  target[pathParts[pathParts.length - 1]] = value;
+}
+
+export async function run(args) {
+  const dryRun = args.includes('--dry-run');
+  const semverArgs = args.filter(a => a !== '--dry-run');
+
+  if (semverArgs.length < 1) {
+    console.error('Usage: tf version <semver> [--dry-run]');
+    process.exit(2);
+  }
+
+  const newVersion = semverArgs[0];
+  const match = newVersion.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    console.error(`Invalid semver: ${newVersion}`);
+    process.exit(2);
+  }
+  const [, , minor, patch] = match;
+
+  console.log(`Version sync → ${newVersion}${dryRun ? ' (dry run)' : ''}\n`);
+  let changed = 0;
+  let unchanged = 0;
+  let skipped = 0;
+
+  // ── Phase 1: JSON manifests ──
+  console.log('── JSON manifests ──');
+  const seenFiles = new Set();
+  for (const manifest of MANIFESTS) {
+    const key = `${manifest.file}:${manifest.path.join('.')}`;
+    if (seenFiles.has(key)) continue;
+    seenFiles.add(key);
+
+    const filePath = join(process.cwd(), manifest.file);
+    if (!existsSync(filePath)) {
+      console.log(`  ⏭️  ${manifest.file} — not found, skipping`);
+      skipped++;
+      continue;
+    }
+
+    const content = JSON.parse(readFileSync(filePath, 'utf-8'));
+    const currentVersion = getNestedValue(content, manifest.path);
+
+    if (currentVersion === newVersion) {
+      console.log(`  ✅ ${manifest.file} [${manifest.path.join('.')}]: ${currentVersion} (unchanged)`);
+      unchanged++;
+    } else {
+      console.log(`  📝 ${manifest.file} [${manifest.path.join('.')}]: ${currentVersion || 'N/A'} → ${newVersion}`);
+      changed++;
+      if (!dryRun) {
+        setNestedValue(content, manifest.path, newVersion);
+        writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n');
+      }
+    }
+  }
+
+  // ── Phase 2: Text files (regex) ──
+  console.log('\n── Documentation & scripts ──');
+  for (const entry of TEXT_FILES) {
+    const filePath = join(process.cwd(), entry.file);
+    if (!existsSync(filePath)) {
+      console.log(`  ⏭️  ${entry.file} — not found, skipping`);
+      skipped++;
+      continue;
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const replacement = entry.replacement
+      .replace('%MINOR%', minor)
+      .replace('%PATCH%', patch);
+
+    const newContent = content.replace(entry.pattern, replacement);
+    if (newContent === content) {
+      console.log(`  ✅ ${entry.file}: no version pattern matched (may already be correct)`);
+      unchanged++;
+    } else {
+      console.log(`  📝 ${entry.file}: version string updated`);
+      changed++;
+      if (!dryRun) {
+        writeFileSync(filePath, newContent);
+      }
+    }
+  }
+
+  console.log(`\n${'─'.repeat(40)}`);
+  console.log(`Changed: ${changed}  Unchanged: ${unchanged}  Skipped: ${skipped}`);
+  if (dryRun) {
+    console.log('\nDry run complete. Run without --dry-run to apply changes.');
+  } else {
+    console.log('\n✅ Version synced across all files. Remember to commit and update CHANGELOG.md.');
+  }
+}