feat: v3.1.0 - Template upgrade feature

- Add template version metadata (<!-- codesyncer-version: X.Y.Z -->)
- Detect outdated templates during `codesyncer update`
- Offer upgrade with automatic backup (.backup.YYYY-MM-DD)
- Preview option before upgrading
- Preserve project variables during upgrade

New files:
- src/utils/template-version.ts
- src/utils/template-upgrader.ts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: snoo

README.ko.md

@@ -237,6 +237,7 @@ codesyncer validate --verbose # 파일 경로 표시
 3. ✅ 언어 설정 자동 감지 (한국어/영어)
 4. ✅ 새 파일 생성 전 사용자 확인 요청
 5. ✅ 기존 커스터마이징 내용 보존
+6. ✅ **v3.1.0 신규**: 구버전 템플릿 감지 및 업그레이드 제안
 
 **출력 예시:**
 ```
@@ -264,6 +265,29 @@ This file allows Claude to automatically load context at session start.
 ✅ Update complete!
 ```
 
+#### 템플릿 업그레이드 (v3.1.0 신규)
+
+CodeSyncer를 새 버전으로 업데이트하면, 기존 템플릿 파일이 구버전일 수 있습니다. `update` 명령어가 이를 자동으로 감지합니다:
+
+```
+📦 새 버전 감지: v3.1.0
+
+  📁 my-project/
+     • CLAUDE.md (v3.0.0 → v3.1.0)
+     • COMMENT_GUIDE.md (버전 없음 → v3.1.0)
+
+? 2개 템플릿을 업그레이드할까요?
+  > 예 - 업그레이드 (기존 파일 .backup으로 백업)
+    아니오 - 건너뛰기
+    미리보기 - 변경 파일만 확인
+```
+
+**기능:**
+- 🔍 버전 메타데이터를 읽어 구버전 템플릿 자동 감지
+- 💾 업그레이드 전 `.backup` 파일 생성 (예: `CLAUDE.md.backup.2024-01-17`)
+- 📋 업그레이드 시 프로젝트 변수 (프로젝트 이름, 기술 스택) 보존
+- 👁️ 변경 사항을 미리 확인하는 미리보기 옵션
+
 **`codesyncer update` 실행 후:**
 
 다음 중 하나를 선택하여 변경사항을 적용하세요:

README.md

@@ -237,6 +237,7 @@ Sync your project with the latest templates and features:
 3. ✅ Auto-detects your language settings (English/Korean)
 4. ✅ Prompts before creating any new files
 5. ✅ Preserves your existing customizations
+6. ✅ **NEW in v3.1.0**: Detects outdated templates and offers upgrade
 
 **Example output:**
 ```
@@ -264,6 +265,29 @@ Option 2) Apply immediately in current session
 ✅ Update complete!
 ```
 
+#### Template Upgrade (NEW in v3.1.0)
+
+When you update CodeSyncer to a new version, your existing template files may be outdated. The `update` command now automatically detects this:
+
+```
+📦 New Version Detected: v3.1.0
+
+  📁 my-project/
+     • CLAUDE.md (v3.0.0 → v3.1.0)
+     • COMMENT_GUIDE.md (no version → v3.1.0)
+
+? Upgrade 2 template(s)?
+  > Yes - Upgrade (backup existing files to .backup)
+    No - Skip
+    Preview - Show files only
+```
+
+**Features:**
+- 🔍 Automatically detects outdated templates by reading version metadata
+- 💾 Creates `.backup` files before upgrading (e.g., `CLAUDE.md.backup.2024-01-17`)
+- 📋 Preserves project variables (project name, tech stack) during upgrade
+- 👁️ Preview option to see what would change
+
 **After running `codesyncer update`:**
 
 Choose one of these options to apply changes:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesyncer",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Claude forgets everything when the session ends. CodeSyncer makes it remember.",
   "keywords": [
     "ai-collaboration",

src/commands/update.ts

@@ -6,6 +6,18 @@ import * as path from 'path';
 import { UpdateOptions, Language, RepositoryInfo } from '../types';
 import { scanForRepositories, hasMasterSetup, detectMonorepo, scanMonorepoPackages } from '../utils/scanner';
 import { getMonorepoToolName } from '../utils/monorepo-helpers';
+import {
+  scanTemplateVersions,
+  getOutdatedTemplates,
+  TemplateStatus,
+  getCurrentVersion,
+} from '../utils/template-version';
+import {
+  upgradeTemplates,
+  getTemplateVarsFromContext,
+  formatUpgradeSummary,
+  UpgradeResult,
+} from '../utils/template-upgrader';
 
 export async function updateCommand(options: UpdateOptions) {
   const isDryRun = options.dryRun || false;
@@ -777,10 +789,168 @@ rm .codesyncer/UPDATE_GUIDE.md
     }
   }
 
+  // Template Upgrade Check
+  await checkAndOfferTemplateUpgrade(currentDir, foundRepos, lang, isDryRun);
+
   if (isDryRun) {
     console.log(chalk.bold.yellow('\n✅ Dry run complete! No files were modified.\n'));
     console.log(chalk.gray('Run without --dry-run to apply changes.\n'));
   } else {
     console.log(chalk.bold.green('\n✅ Update complete!\n'));
   }
 }
+
+/**
+ * Check for outdated templates and offer upgrade option
+ *
+ * @codesyncer-context Template upgrade feature - checks version metadata in files
+ * @codesyncer-decision [2026-01-17] Backup files before upgrade for user safety
+ */
+async function checkAndOfferTemplateUpgrade(
+  currentDir: string,
+  repos: RepositoryInfo[],
+  lang: Language,
+  isDryRun: boolean
+): Promise<void> {
+  const currentVersion = getCurrentVersion();
+
+  // Collect all outdated templates across all repos
+  const allOutdated: { repo: string; claudeDir: string; templates: TemplateStatus[] }[] = [];
+
+  for (const repo of repos) {
+    const claudeDir = path.join(repo.path, '.claude');
+    if (await fs.pathExists(claudeDir)) {
+      const outdated = await getOutdatedTemplates(claudeDir);
+      if (outdated.length > 0) {
+        allOutdated.push({
+          repo: repo.name,
+          claudeDir,
+          templates: outdated,
+        });
+      }
+    }
+  }
+
+  // Also check root .claude if it exists (for single repo setup)
+  const rootClaudeDir = path.join(currentDir, '.claude');
+  if (await fs.pathExists(rootClaudeDir)) {
+    const rootOutdated = await getOutdatedTemplates(rootClaudeDir);
+    if (rootOutdated.length > 0) {
+      // Avoid duplicates
+      const alreadyIncluded = allOutdated.some((o) => o.claudeDir === rootClaudeDir);
+      if (!alreadyIncluded) {
+        allOutdated.push({
+          repo: path.basename(currentDir),
+          claudeDir: rootClaudeDir,
+          templates: rootOutdated,
+        });
+      }
+    }
+  }
+
+  if (allOutdated.length === 0) {
+    return; // No outdated templates found
+  }
+
+  // Count total outdated files
+  const totalOutdated = allOutdated.reduce((sum, o) => sum + o.templates.length, 0);
+
+  // Display upgrade notification
+  console.log(chalk.bold.blue('\n📦 ' + (lang === 'ko' ? '새 버전 감지' : 'New Version Detected') + `: v${currentVersion}\n`));
+
+  // Show outdated files grouped by repo
+  allOutdated.forEach(({ repo, templates }) => {
+    console.log(chalk.yellow(`  📁 ${repo}/`));
+    templates.forEach((t) => {
+      const fileName = path.basename(t.file);
+      const versionInfo = t.currentVersion
+        ? `v${t.currentVersion} → v${t.latestVersion}`
+        : `(${lang === 'ko' ? '버전 없음' : 'no version'}) → v${t.latestVersion}`;
+      console.log(chalk.gray(`     • ${fileName} (${versionInfo})`));
+    });
+  });
+  console.log();
+
+  // Prompt for upgrade
+  const { upgradeChoice } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'upgradeChoice',
+      message: lang === 'ko'
+        ? `${totalOutdated}개 템플릿을 업그레이드할까요?`
+        : `Upgrade ${totalOutdated} template(s)?`,
+      choices: [
+        {
+          name: lang === 'ko'
+            ? '예 - 업그레이드 (기존 파일 .backup으로 백업)'
+            : 'Yes - Upgrade (backup existing files to .backup)',
+          value: 'yes',
+        },
+        {
+          name: lang === 'ko' ? '아니오 - 건너뛰기' : 'No - Skip',
+          value: 'no',
+        },
+        {
+          name: lang === 'ko' ? '미리보기 - 변경 파일만 확인' : 'Preview - Show files only',
+          value: 'preview',
+        },
+      ],
+      default: 'yes',
+    },
+  ]);
+
+  if (upgradeChoice === 'preview') {
+    console.log(chalk.bold('\n' + (lang === 'ko' ? '📋 업그레이드 대상 파일:' : '📋 Files to upgrade:')));
+    allOutdated.forEach(({ repo, templates }) => {
+      templates.forEach((t) => {
+        console.log(chalk.gray(`  • ${repo}/.claude/${path.basename(t.file)}`));
+      });
+    });
+    console.log();
+    return;
+  }
+
+  if (upgradeChoice === 'no') {
+    console.log(chalk.gray(lang === 'ko' ? '  템플릿 업그레이드 건너뜀\n' : '  Template upgrade skipped\n'));
+    return;
+  }
+
+  // Perform upgrade
+  if (isDryRun) {
+    console.log(chalk.yellow(lang === 'ko'
+      ? '\n  [DRY RUN] 업그레이드 수행됨 (실제 파일 변경 없음)\n'
+      : '\n  [DRY RUN] Upgrade would be performed (no actual changes)\n'));
+    allOutdated.forEach(({ repo, templates }) => {
+      templates.forEach((t) => {
+        console.log(chalk.gray(`  • ${repo}/.claude/${path.basename(t.file)}`));
+      });
+    });
+    return;
+  }
+
+  const spinner = ora(lang === 'ko' ? '템플릿 업그레이드 중...' : 'Upgrading templates...').start();
+
+  const allResults: UpgradeResult[] = [];
+
+  for (const { claudeDir, templates } of allOutdated) {
+    const vars = await getTemplateVarsFromContext(claudeDir, lang);
+    const results = await upgradeTemplates(templates, { lang, vars, dryRun: isDryRun });
+    allResults.push(...results);
+  }
+
+  spinner.succeed(lang === 'ko' ? '템플릿 업그레이드 완료!' : 'Templates upgraded!');
+
+  // Show summary
+  console.log();
+  console.log(formatUpgradeSummary(allResults, lang));
+  console.log();
+
+  // Show backup notice
+  const successfulWithBackup = allResults.filter((r) => r.success && r.backupPath);
+  if (successfulWithBackup.length > 0) {
+    console.log(chalk.cyan(lang === 'ko'
+      ? '💡 백업 파일에서 커스터마이징 내용을 복사할 수 있습니다.'
+      : '💡 You can copy customizations from backup files.'));
+    console.log();
+  }
+}

src/templates/en/architecture.md

@@ -145,3 +145,5 @@ No API endpoints discovered.
 ---
 
 *This document is auto-generated and managed by CodeSyncer.*
+
+<!-- codesyncer-version: 3.1.0 -->

src/templates/en/claude.md

@@ -279,3 +279,5 @@ grep -r "@codesyncer-rule" ./
 ---
 
 *This collaboration system is open source. Suggest improvements at [CodeSyncer GitHub](https://github.com/bitjaru/codesyncer)!*
+
+<!-- codesyncer-version: 3.1.0 -->

src/templates/en/comment_guide.md

@@ -580,3 +580,5 @@ After writing code:
 **Last Updated**: [TODAY]
 
 *Comments are the documentation. Record all context in code.*
+
+<!-- codesyncer-version: 3.1.0 -->

src/templates/en/decisions.md

@@ -225,3 +225,5 @@ grep "@codesyncer-decision" src/services/PaymentService.ts
 **Last Updated**: [TODAY]
 
 *All important decisions are permanently recorded. This is your team's knowledge asset.*
+
+<!-- codesyncer-version: 3.1.0 -->

src/templates/en/master.md

@@ -177,3 +177,5 @@ Both formats work identically, so use whichever you prefer!
 
 *CodeSyncer - Persistent context, controlled inference, live architecture sync for Claude Code*
 *Currently Supported: Claude Code | Coming Soon: Cursor, GitHub Copilot, Continue.dev*
+
+<!-- codesyncer-version: 3.1.0 -->

src/templates/en/root_claude.md

@@ -239,3 +239,5 @@ grep -r "payment" ./*/
 ---
 
 *CodeSyncer is open source: https://github.com/bitjaru/codesyncer*
+
+<!-- codesyncer-version: 3.1.0 -->