omgkit 2.24.3 → 2.25.0

package/README.md

@@ -747,6 +747,8 @@ Generated in `.omgkit/stdrules/` when you run `omgkit init`:
 
 ## CLI Commands
 
+### Global Commands
+
 ```bash
 omgkit install      # Install plugin to Claude Code
 omgkit init         # Initialize .omgkit/ in project
@@ -757,6 +759,41 @@ omgkit uninstall    # Remove plugin
 omgkit help         # Show help
 ```
 
+### Project Upgrade Commands (New)
+
+Keep your project up-to-date with the latest OMGKIT features:
+
+```bash
+omgkit project:upgrade     # Upgrade project to latest OMGKIT version
+omgkit project:upgrade --dry  # Preview changes without applying
+omgkit project:rollback    # Rollback to previous backup
+omgkit project:backups     # List available backups
+omgkit project:version     # Show project's OMGKIT version
+```
+
+#### Safe Upgrade System
+
+OMGKIT's upgrade system is designed with safety first:
+
+| Feature | Description |
+|---------|-------------|
+| **Version Tracking** | Each project tracks its OMGKIT version in settings.json |
+| **Smart Merge** | workflow.yaml uses add-only merge (never overwrites your values) |
+| **Protected Files** | config.yaml, sprints/*, artifacts/*, devlogs/* are NEVER modified |
+| **Auto-Backup** | Creates timestamped backup before any changes |
+| **Dry Run** | Preview all changes with `--dry` flag before applying |
+| **Rollback** | One command to restore previous state if needed |
+
+#### What Gets Upgraded
+
+| File Type | Upgrade Behavior |
+|-----------|-----------------|
+| **stdrules/** | New standards are added, modified ones offer 3-way merge |
+| **workflow.yaml** | Smart merge adds new sections, preserves your customizations |
+| **CLAUDE.md** | Updated with new instructions |
+| **settings.json** | Version updated, structure preserved |
+| **Your files** | NEVER touched (config.yaml, sprints, artifacts, devlogs) |
+
 ---
 
 ## Documentation Sync Automation

package/bin/omgkit.js

@@ -21,6 +21,10 @@ import {
   doctor,
   uninstallPlugin,
   listComponents,
+  upgradeProject,
+  rollbackProject,
+  listProjectBackups,
+  getProjectVersion,
   COLORS,
   BANNER,
   log
@@ -37,21 +41,33 @@ function showHelp() {
 ${COLORS.bright}USAGE${COLORS.reset}
   omgkit <command> [options]
 
-${COLORS.bright}COMMANDS${COLORS.reset}
-  ${COLORS.cyan}install${COLORS.reset}    Install OMGKIT plugin to Claude Code
-  ${COLORS.cyan}init${COLORS.reset}       Initialize .omgkit/ in current project
-  ${COLORS.cyan}update${COLORS.reset}     Update OMGKIT plugin
-  ${COLORS.cyan}uninstall${COLORS.reset}  Remove OMGKIT plugin
-  ${COLORS.cyan}doctor${COLORS.reset}     Check installation status
-  ${COLORS.cyan}list${COLORS.reset}       List all commands/agents/skills
-  ${COLORS.cyan}version${COLORS.reset}    Show version
-  ${COLORS.cyan}help${COLORS.reset}       Show this help
+${COLORS.bright}GLOBAL COMMANDS${COLORS.reset}
+  ${COLORS.cyan}install${COLORS.reset}           Install OMGKIT plugin to Claude Code
+  ${COLORS.cyan}update${COLORS.reset}            Update OMGKIT plugin (same as install)
+  ${COLORS.cyan}uninstall${COLORS.reset}         Remove OMGKIT plugin
+  ${COLORS.cyan}doctor${COLORS.reset}            Check installation status
+  ${COLORS.cyan}list${COLORS.reset}              List all commands/agents/skills
+  ${COLORS.cyan}version${COLORS.reset}           Show version
+  ${COLORS.cyan}help${COLORS.reset}              Show this help
+
+${COLORS.bright}PROJECT COMMANDS${COLORS.reset}
+  ${COLORS.cyan}init${COLORS.reset}              Initialize .omgkit/ in current project
+  ${COLORS.cyan}project:upgrade${COLORS.reset}   Upgrade project to latest OMGKIT version
+  ${COLORS.cyan}project:rollback${COLORS.reset}  Rollback project to previous backup
+  ${COLORS.cyan}project:backups${COLORS.reset}   List available project backups
+  ${COLORS.cyan}project:version${COLORS.reset}   Show project's OMGKIT version
+
+${COLORS.bright}UPGRADE OPTIONS${COLORS.reset}
+  --dry        Show what would change without applying
+  --force      Skip confirmation prompts
 
 ${COLORS.bright}EXAMPLES${COLORS.reset}
-  omgkit install          # Install plugin globally
-  omgkit init             # Initialize project
-  omgkit doctor           # Check status
-  omgkit list commands    # List all commands
+  omgkit install               # Install plugin globally
+  omgkit init                  # Initialize project
+  omgkit project:upgrade       # Upgrade project config
+  omgkit project:upgrade --dry # Preview upgrade changes
+  omgkit project:rollback      # Rollback to last backup
+  omgkit doctor                # Check status
 
 ${COLORS.bright}AFTER INSTALLATION${COLORS.reset}
   In Claude Code, type / to see all OMGKIT commands:
@@ -59,7 +75,7 @@ ${COLORS.bright}AFTER INSTALLATION${COLORS.reset}
   Core: /dev:feature, /dev:fix, /planning:plan, /quality:test, /dev:review
   Omega: /omega:10x, /omega:100x, /omega:1000x, /omega:principles
   Sprint: /sprint:vision-set, /sprint:sprint-new, /sprint:team-run
-  Workflow: /workflow:init, /workflow:status, /hooks:setup
+  Testing: /quality:verify-done, /quality:coverage-check, /quality:test-plan
 
 ${COLORS.bright}DOCUMENTATION${COLORS.reset}
   https://omg.mintlify.app
@@ -102,6 +118,44 @@ switch (command) {
     if (!result.success) process.exit(1);
     break;
   }
+  case 'project:upgrade': {
+    const dryRun = args.includes('--dry');
+    const force = args.includes('--force');
+    const result = upgradeProject({ dryRun, force });
+    if (!result.success && !result.upToDate) process.exit(1);
+    break;
+  }
+  case 'project:rollback': {
+    const result = rollbackProject();
+    if (!result.success) process.exit(1);
+    break;
+  }
+  case 'project:backups': {
+    console.log(BANNER);
+    const backups = listProjectBackups();
+    if (backups.length === 0) {
+      log.info('No backups found');
+    } else {
+      console.log(`${COLORS.bright}Available Backups${COLORS.reset}\n`);
+      backups.forEach((backup, i) => {
+        const age = Math.round((Date.now() - backup.created) / 1000 / 60);
+        const ageStr = age < 60 ? `${age} minutes ago` : `${Math.round(age / 60)} hours ago`;
+        console.log(`  ${i + 1}. ${backup.name} (${ageStr})`);
+      });
+      console.log(`\nTo restore: omgkit project:rollback`);
+    }
+    break;
+  }
+  case 'project:version': {
+    const projectVersion = getProjectVersion();
+    const omgkitVersion = getVersion();
+    console.log(`Project OMGKIT version: ${projectVersion || 'not tracked (older project)'}`);
+    console.log(`Current OMGKIT version: ${omgkitVersion}`);
+    if (projectVersion && projectVersion !== omgkitVersion) {
+      log.info('Run: omgkit project:upgrade');
+    }
+    break;
+  }
   case 'version':
   case '-v':
   case '--version': {

package/lib/cli.js

@@ -393,21 +393,33 @@ export function initProject(options = {}) {
     { src: 'CLAUDE.md', dest: 'CLAUDE.md' },
     { src: 'vision.yaml', dest: '.omgkit/sprints/vision.yaml' },
     { src: 'backlog.yaml', dest: '.omgkit/sprints/backlog.yaml' },
-    { src: 'settings.json', dest: '.omgkit/settings.json' },
+    { src: 'settings.json', dest: '.omgkit/settings.json', process: true },
     { src: 'devlogs/README.md', dest: '.omgkit/devlogs/README.md' },
     { src: 'stdrules/README.md', dest: '.omgkit/stdrules/README.md' },
     { src: 'stdrules/SKILL_STANDARDS.md', dest: '.omgkit/stdrules/SKILL_STANDARDS.md' },
     { src: 'stdrules/BEFORE_COMMIT.md', dest: '.omgkit/stdrules/BEFORE_COMMIT.md' },
     { src: 'stdrules/TESTING_STANDARDS.md', dest: '.omgkit/stdrules/TESTING_STANDARDS.md' },
-    { src: 'artifacts/README.md', dest: '.omgkit/artifacts/README.md' }
+    { src: 'artifacts/README.md', dest: '.omgkit/artifacts/README.md' },
+    { src: 'omgkit/workflow.yaml', dest: '.omgkit/workflow.yaml' }
   ];
 
-  templates.forEach(({ src, dest }) => {
+  const version = getVersion();
+  const initDate = new Date().toISOString().split('T')[0];
+
+  templates.forEach(({ src, dest, process: shouldProcess }) => {
     const srcPath = join(templatesDir, src);
     const destPath = join(cwd, dest);
 
     if (existsSync(srcPath) && !existsSync(destPath)) {
-      cpSync(srcPath, destPath);
+      if (shouldProcess) {
+        // Process template placeholders
+        let content = readFileSync(srcPath, 'utf8');
+        content = content.replace(/\{\{OMGKIT_VERSION\}\}/g, version);
+        content = content.replace(/\{\{INIT_DATE\}\}/g, initDate);
+        writeFileSync(destPath, content);
+      } else {
+        cpSync(srcPath, destPath);
+      }
       createdFiles.push(dest);
       if (!silent) log.success(`Created ${dest}`);
     }
@@ -934,3 +946,690 @@ export function validatePluginFile(filePath, requiredFields = []) {
   result.frontmatter = frontmatter;
   return result;
 }
+
+// ============================================================================
+// PROJECT UPGRADE SYSTEM
+// ============================================================================
+
+/**
+ * Create a hash of file content for change detection
+ * @param {string} content - File content
+ * @returns {string} Hash string
+ */
+function hashContent(content) {
+  let hash = 0;
+  for (let i = 0; i < content.length; i++) {
+    const char = content.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  return hash.toString(16);
+}
+
+/**
+ * Deep merge two objects (for YAML config merging)
+ * Only adds new keys, never overwrites existing values
+ * @param {Object} target - Target object (user's config)
+ * @param {Object} source - Source object (new template)
+ * @returns {Object} Merged object
+ */
+function deepMergeAddOnly(target, source) {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    if (!(key in result)) {
+      // Key doesn't exist in target, add it
+      result[key] = source[key];
+    } else if (
+      typeof result[key] === 'object' &&
+      result[key] !== null &&
+      !Array.isArray(result[key]) &&
+      typeof source[key] === 'object' &&
+      source[key] !== null &&
+      !Array.isArray(source[key])
+    ) {
+      // Both are objects, recurse
+      result[key] = deepMergeAddOnly(result[key], source[key]);
+    }
+    // If key exists and is not an object, keep user's value
+  }
+
+  return result;
+}
+
+/**
+ * Simple YAML parser for config files
+ * @param {string} content - YAML content
+ * @returns {Object} Parsed object
+ */
+function parseSimpleYaml(content) {
+  const result = {};
+  const lines = content.split('\n');
+  const stack = [{ obj: result, indent: -1 }];
+
+  for (const line of lines) {
+    // Skip comments and empty lines
+    if (line.trim().startsWith('#') || line.trim() === '') continue;
+
+    const indent = line.search(/\S/);
+    if (indent === -1) continue;
+
+    const trimmed = line.trim();
+
+    // Pop stack to find parent
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+
+    const parent = stack[stack.length - 1].obj;
+
+    if (trimmed.startsWith('- ')) {
+      // Array item
+      const value = trimmed.substring(2).trim();
+      if (!Array.isArray(parent)) {
+        // Find the key that should be an array
+        const keys = Object.keys(parent);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && parent[lastKey] === null) {
+          parent[lastKey] = [value];
+        }
+      } else {
+        parent.push(value);
+      }
+    } else if (trimmed.includes(':')) {
+      const colonIndex = trimmed.indexOf(':');
+      const key = trimmed.substring(0, colonIndex).trim();
+      let value = trimmed.substring(colonIndex + 1).trim();
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      if (value === '' || value === null) {
+        // Object or array follows
+        parent[key] = {};
+        stack.push({ obj: parent[key], indent });
+      } else if (value === 'true') {
+        parent[key] = true;
+      } else if (value === 'false') {
+        parent[key] = false;
+      } else if (!isNaN(Number(value)) && value !== '') {
+        parent[key] = Number(value);
+      } else {
+        parent[key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Serialize object to simple YAML
+ * @param {Object} obj - Object to serialize
+ * @param {number} indent - Current indentation level
+ * @returns {string} YAML string
+ */
+function toSimpleYaml(obj, indent = 0) {
+  const spaces = '  '.repeat(indent);
+  let result = '';
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) {
+      result += `${spaces}${key}:\n`;
+    } else if (Array.isArray(value)) {
+      result += `${spaces}${key}:\n`;
+      for (const item of value) {
+        if (typeof item === 'object') {
+          result += `${spaces}  -\n${toSimpleYaml(item, indent + 2)}`;
+        } else {
+          result += `${spaces}  - ${item}\n`;
+        }
+      }
+    } else if (typeof value === 'object') {
+      result += `${spaces}${key}:\n${toSimpleYaml(value, indent + 1)}`;
+    } else if (typeof value === 'string' && (value.includes(':') || value.includes('#'))) {
+      result += `${spaces}${key}: "${value}"\n`;
+    } else {
+      result += `${spaces}${key}: ${value}\n`;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get project settings including version info
+ * @param {string} cwd - Project directory
+ * @returns {Object|null} Settings object or null
+ */
+export function getProjectSettings(cwd = process.cwd()) {
+  const settingsPath = join(cwd, '.omgkit', 'settings.json');
+  if (!existsSync(settingsPath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(settingsPath, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Get project version
+ * @param {string} cwd - Project directory
+ * @returns {string|null} Version string or null
+ */
+export function getProjectVersion(cwd = process.cwd()) {
+  const settings = getProjectSettings(cwd);
+  return settings?.omgkit?.version || null;
+}
+
+/**
+ * Compare semantic versions
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Create backup of .omgkit directory
+ * @param {string} cwd - Project directory
+ * @returns {Object} Backup result with path
+ */
+export function createProjectBackup(cwd = process.cwd()) {
+  const omgkitDir = join(cwd, '.omgkit');
+  if (!existsSync(omgkitDir)) {
+    return { success: false, error: 'NOT_INITIALIZED' };
+  }
+
+  const now = new Date();
+  const timestamp = now.toISOString().replace(/[:.]/g, '-').split('T').join('-').substring(0, 19);
+  const ms = String(now.getMilliseconds()).padStart(3, '0');
+  const backupDir = join(cwd, `.omgkit-backup-${timestamp}-${ms}`);
+
+  try {
+    cpSync(omgkitDir, backupDir, { recursive: true });
+    return { success: true, path: backupDir, timestamp };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * List available backups
+ * @param {string} cwd - Project directory
+ * @returns {Object[]} Array of backup info
+ */
+export function listProjectBackups(cwd = process.cwd()) {
+  const backups = [];
+
+  try {
+    const items = readdirSync(cwd);
+    for (const item of items) {
+      if (item.startsWith('.omgkit-backup-')) {
+        const fullPath = join(cwd, item);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          backups.push({
+            name: item,
+            path: fullPath,
+            created: stat.mtime
+          });
+        }
+      }
+    }
+  } catch (e) {
+    // Directory read error
+  }
+
+  return backups.sort((a, b) => b.created - a.created);
+}
+
+/**
+ * Rollback project to a backup
+ * @param {Object} options - Options
+ * @param {string} [options.cwd] - Project directory
+ * @param {string} [options.backupPath] - Specific backup to restore
+ * @param {boolean} [options.silent] - Suppress output
+ * @returns {Object} Result
+ */
+export function rollbackProject(options = {}) {
+  const { cwd = process.cwd(), backupPath, silent = false } = options;
+
+  if (!silent) {
+    console.log(BANNER);
+    log.omega('Rolling back project...');
+  }
+
+  const omgkitDir = join(cwd, '.omgkit');
+  let targetBackup = backupPath;
+
+  if (!targetBackup) {
+    // Find most recent backup
+    const backups = listProjectBackups(cwd);
+    if (backups.length === 0) {
+      if (!silent) log.error('No backups found');
+      return { success: false, error: 'NO_BACKUPS' };
+    }
+    targetBackup = backups[0].path;
+  }
+
+  if (!existsSync(targetBackup)) {
+    if (!silent) log.error(`Backup not found: ${targetBackup}`);
+    return { success: false, error: 'BACKUP_NOT_FOUND' };
+  }
+
+  try {
+    // Remove current .omgkit
+    if (existsSync(omgkitDir)) {
+      rmSync(omgkitDir, { recursive: true, force: true });
+    }
+
+    // Restore from backup
+    cpSync(targetBackup, omgkitDir, { recursive: true });
+
+    if (!silent) {
+      log.success(`Rolled back to: ${targetBackup}`);
+    }
+
+    return { success: true, restoredFrom: targetBackup };
+  } catch (e) {
+    if (!silent) log.error(`Rollback failed: ${e.message}`);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Calculate upgrade changes (dry run)
+ * @param {string} cwd - Project directory
+ * @returns {Object} Changes to be applied
+ */
+export function calculateUpgradeChanges(cwd = process.cwd()) {
+  const changes = {
+    settings: [],
+    workflow: [],
+    stdrules: [],
+    newFiles: [],
+    protected: [
+      'config.yaml',
+      'sprints/vision.yaml',
+      'sprints/backlog.yaml',
+      'artifacts/*',
+      'devlogs/*'
+    ]
+  };
+
+  const templatesDir = join(getPackageRoot(), 'templates');
+  const omgkitDir = join(cwd, '.omgkit');
+  const currentVersion = getProjectVersion(cwd);
+  const targetVersion = getVersion();
+
+  // Check workflow.yaml changes
+  const workflowTemplatePath = join(templatesDir, 'omgkit', 'workflow.yaml');
+  const workflowProjectPath = join(omgkitDir, 'workflow.yaml');
+
+  if (existsSync(workflowTemplatePath)) {
+    const templateContent = readFileSync(workflowTemplatePath, 'utf8');
+    const templateConfig = parseSimpleYaml(templateContent);
+
+    if (existsSync(workflowProjectPath)) {
+      const projectContent = readFileSync(workflowProjectPath, 'utf8');
+      const projectConfig = parseSimpleYaml(projectContent);
+
+      // Find new top-level sections
+      for (const key of Object.keys(templateConfig)) {
+        if (!(key in projectConfig)) {
+          changes.workflow.push({
+            type: 'add_section',
+            key,
+            value: templateConfig[key]
+          });
+        }
+      }
+    } else {
+      changes.newFiles.push('workflow.yaml');
+    }
+  }
+
+  // Check stdrules updates
+  const stdrulesTemplate = join(templatesDir, 'stdrules');
+  const stdrulesProject = join(omgkitDir, 'stdrules');
+
+  if (existsSync(stdrulesTemplate)) {
+    const templateFiles = readdirSync(stdrulesTemplate).filter(f => f.endsWith('.md'));
+    const settings = getProjectSettings(cwd) || {};
+    const checksums = settings.file_checksums || {};
+
+    for (const file of templateFiles) {
+      const templatePath = join(stdrulesTemplate, file);
+      const projectPath = join(stdrulesProject, file);
+      const templateContent = readFileSync(templatePath, 'utf8');
+      const templateHash = hashContent(templateContent);
+
+      if (!existsSync(projectPath)) {
+        changes.stdrules.push({
+          type: 'new',
+          file,
+          reason: 'File does not exist'
+        });
+      } else {
+        const projectContent = readFileSync(projectPath, 'utf8');
+        const projectHash = hashContent(projectContent);
+        const originalHash = checksums[`stdrules/${file}`];
+
+        // Update only if user hasn't modified the file
+        if (originalHash && projectHash === originalHash && templateHash !== projectHash) {
+          changes.stdrules.push({
+            type: 'update',
+            file,
+            reason: 'Template updated, user has not modified'
+          });
+        } else if (!originalHash && templateHash !== projectHash) {
+          changes.stdrules.push({
+            type: 'skip',
+            file,
+            reason: 'User may have modified (no checksum recorded)'
+          });
+        }
+      }
+    }
+  }
+
+  // Settings.json updates
+  const settingsPath = join(omgkitDir, 'settings.json');
+  if (existsSync(settingsPath)) {
+    const settings = getProjectSettings(cwd);
+    if (!settings?.omgkit) {
+      changes.settings.push({
+        type: 'add',
+        key: 'omgkit',
+        value: { version: targetVersion, initialized_at: null, last_upgraded: null }
+      });
+    }
+    if (!settings?.file_checksums) {
+      changes.settings.push({
+        type: 'add',
+        key: 'file_checksums',
+        value: {}
+      });
+    }
+  }
+
+  return {
+    currentVersion,
+    targetVersion,
+    needsUpgrade: compareVersions(targetVersion, currentVersion || '0.0.0') > 0,
+    changes
+  };
+}
+
+/**
+ * Upgrade project to latest OMGKIT version
+ * @param {Object} options - Options
+ * @param {string} [options.cwd] - Project directory
+ * @param {boolean} [options.dryRun] - Only show what would change
+ * @param {boolean} [options.force] - Skip confirmation
+ * @param {boolean} [options.silent] - Suppress output
+ * @returns {Object} Upgrade result
+ */
+export function upgradeProject(options = {}) {
+  const { cwd = process.cwd(), dryRun = false, force = false, silent = false } = options;
+
+  if (!silent) {
+    console.log(BANNER);
+    log.omega('Checking for project upgrades...');
+  }
+
+  const omgkitDir = join(cwd, '.omgkit');
+
+  // Check if project is initialized
+  if (!existsSync(omgkitDir)) {
+    if (!silent) {
+      log.error('Project not initialized. Run: omgkit init');
+    }
+    return { success: false, error: 'NOT_INITIALIZED' };
+  }
+
+  // Calculate changes
+  const upgradeInfo = calculateUpgradeChanges(cwd);
+
+  if (!upgradeInfo.needsUpgrade &&
+      upgradeInfo.changes.workflow.length === 0 &&
+      upgradeInfo.changes.stdrules.filter(s => s.type !== 'skip').length === 0 &&
+      upgradeInfo.changes.newFiles.length === 0) {
+    if (!silent) {
+      log.success('Project is up to date!');
+      console.log(`  Current version: ${upgradeInfo.currentVersion || 'unknown'}`);
+      console.log(`  OMGKIT version: ${upgradeInfo.targetVersion}`);
+    }
+    return { success: true, upToDate: true };
+  }
+
+  // Display changes
+  if (!silent) {
+    console.log(`
+${COLORS.bright}OMGKIT Project Upgrade${COLORS.reset}
+${'='.repeat(50)}
+Current version: ${upgradeInfo.currentVersion || 'unknown'}
+Target version:  ${upgradeInfo.targetVersion}
+
+${COLORS.bright}Changes to be applied:${COLORS.reset}
+`);
+
+    if (upgradeInfo.changes.workflow.length > 0) {
+      console.log(`${COLORS.cyan}📁 workflow.yaml${COLORS.reset}`);
+      for (const change of upgradeInfo.changes.workflow) {
+        if (change.type === 'add_section') {
+          console.log(`   ${COLORS.green}+ ${change.key}: {...}${COLORS.reset}`);
+        }
+      }
+    }
+
+    if (upgradeInfo.changes.stdrules.length > 0) {
+      console.log(`\n${COLORS.cyan}📁 stdrules/${COLORS.reset}`);
+      for (const change of upgradeInfo.changes.stdrules) {
+        if (change.type === 'new') {
+          console.log(`   ${COLORS.green}+ ${change.file} (new)${COLORS.reset}`);
+        } else if (change.type === 'update') {
+          console.log(`   ${COLORS.yellow}~ ${change.file} (updated)${COLORS.reset}`);
+        } else if (change.type === 'skip') {
+          console.log(`   ${COLORS.blue}○ ${change.file} (skipped - may be modified)${COLORS.reset}`);
+        }
+      }
+    }
+
+    if (upgradeInfo.changes.newFiles.length > 0) {
+      console.log(`\n${COLORS.cyan}📁 New files${COLORS.reset}`);
+      for (const file of upgradeInfo.changes.newFiles) {
+        console.log(`   ${COLORS.green}+ ${file}${COLORS.reset}`);
+      }
+    }
+
+    console.log(`
+${COLORS.bright}🔒 Protected (no changes):${COLORS.reset}`);
+    for (const protected_ of upgradeInfo.changes.protected) {
+      console.log(`   - ${protected_}`);
+    }
+  }
+
+  if (dryRun) {
+    if (!silent) {
+      console.log(`\n${COLORS.yellow}Dry run - no changes made.${COLORS.reset}`);
+      console.log('Run without --dry to apply changes.');
+    }
+    return { success: true, dryRun: true, changes: upgradeInfo.changes };
+  }
+
+  // Create backup before upgrade
+  if (!silent) log.info('\nCreating backup...');
+  const backup = createProjectBackup(cwd);
+  if (!backup.success) {
+    if (!silent) log.error(`Backup failed: ${backup.error}`);
+    return { success: false, error: 'BACKUP_FAILED' };
+  }
+  if (!silent) log.success(`Backup created: ${backup.path}`);
+
+  const templatesDir = join(getPackageRoot(), 'templates');
+  const applied = { workflow: [], stdrules: [], newFiles: [], settings: [] };
+
+  try {
+    // Apply workflow.yaml changes
+    if (upgradeInfo.changes.workflow.length > 0) {
+      const workflowPath = join(omgkitDir, 'workflow.yaml');
+      const workflowTemplatePath = join(templatesDir, 'omgkit', 'workflow.yaml');
+
+      if (existsSync(workflowPath) && existsSync(workflowTemplatePath)) {
+        const projectContent = readFileSync(workflowPath, 'utf8');
+        const templateContent = readFileSync(workflowTemplatePath, 'utf8');
+
+        const projectConfig = parseSimpleYaml(projectContent);
+        const templateConfig = parseSimpleYaml(templateContent);
+
+        const merged = deepMergeAddOnly(projectConfig, templateConfig);
+
+        // Preserve comments from original file by appending new sections
+        let newContent = projectContent;
+
+        for (const change of upgradeInfo.changes.workflow) {
+          if (change.type === 'add_section') {
+            // Find section in template and append
+            const sectionRegex = new RegExp(`^${change.key}:`, 'm');
+            const templateLines = templateContent.split('\n');
+            let inSection = false;
+            let sectionContent = '';
+
+            for (const line of templateLines) {
+              if (line.match(sectionRegex)) {
+                inSection = true;
+              } else if (inSection && line.match(/^\w+:/) && !line.startsWith(' ')) {
+                break;
+              }
+
+              if (inSection) {
+                sectionContent += line + '\n';
+              }
+            }
+
+            if (sectionContent) {
+              newContent = newContent.trimEnd() + '\n\n' + sectionContent;
+              applied.workflow.push(change.key);
+            }
+          }
+        }
+
+        writeFileSync(workflowPath, newContent);
+      }
+    }
+
+    // Apply stdrules updates
+    for (const change of upgradeInfo.changes.stdrules) {
+      if (change.type === 'new' || change.type === 'update') {
+        const templatePath = join(templatesDir, 'stdrules', change.file);
+        const projectPath = join(omgkitDir, 'stdrules', change.file);
+
+        if (existsSync(templatePath)) {
+          cpSync(templatePath, projectPath);
+          applied.stdrules.push(change.file);
+        }
+      }
+    }
+
+    // Apply new files
+    for (const file of upgradeInfo.changes.newFiles) {
+      if (file === 'workflow.yaml') {
+        const templatePath = join(templatesDir, 'omgkit', 'workflow.yaml');
+        const projectPath = join(omgkitDir, 'workflow.yaml');
+        if (existsSync(templatePath)) {
+          cpSync(templatePath, projectPath);
+          applied.newFiles.push(file);
+        }
+      }
+    }
+
+    // Update settings.json
+    const settingsPath = join(omgkitDir, 'settings.json');
+    let settings = getProjectSettings(cwd) || {};
+
+    // Add omgkit version tracking
+    if (!settings.omgkit) {
+      settings.omgkit = {};
+    }
+    settings.omgkit.version = upgradeInfo.targetVersion;
+    settings.omgkit.last_upgraded = new Date().toISOString().split('T')[0];
+
+    // Initialize checksums if not present
+    if (!settings.file_checksums) {
+      settings.file_checksums = {};
+    }
+
+    // Update checksums for stdrules files
+    const stdrulesDir = join(omgkitDir, 'stdrules');
+    if (existsSync(stdrulesDir)) {
+      const files = readdirSync(stdrulesDir).filter(f => f.endsWith('.md'));
+      for (const file of files) {
+        const content = readFileSync(join(stdrulesDir, file), 'utf8');
+        settings.file_checksums[`stdrules/${file}`] = hashContent(content);
+      }
+    }
+
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    applied.settings.push('version', 'checksums');
+
+  } catch (e) {
+    // Rollback on error
+    if (!silent) {
+      log.error(`Upgrade failed: ${e.message}`);
+      log.info('Rolling back...');
+    }
+    rollbackProject({ cwd, backupPath: backup.path, silent: true });
+    if (!silent) log.success('Rolled back to previous state');
+    return { success: false, error: e.message, rolledBack: true };
+  }
+
+  if (!silent) {
+    console.log(`
+${COLORS.green}✓ Project upgraded successfully!${COLORS.reset}
+
+${COLORS.bright}Applied changes:${COLORS.reset}`);
+
+    if (applied.workflow.length > 0) {
+      console.log(`  workflow.yaml: Added ${applied.workflow.join(', ')}`);
+    }
+    if (applied.stdrules.length > 0) {
+      console.log(`  stdrules/: Updated ${applied.stdrules.join(', ')}`);
+    }
+    if (applied.newFiles.length > 0) {
+      console.log(`  New files: ${applied.newFiles.join(', ')}`);
+    }
+
+    console.log(`
+${COLORS.bright}Backup location:${COLORS.reset} ${backup.path}
+
+To rollback: omgkit project:rollback
+
+${COLORS.magenta}🔮 Think Omega. Build Omega. Be Omega.${COLORS.reset}
+`);
+  }
+
+  return {
+    success: true,
+    previousVersion: upgradeInfo.currentVersion,
+    newVersion: upgradeInfo.targetVersion,
+    applied,
+    backupPath: backup.path
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgkit",
-  "version": "2.24.3",
+  "version": "2.25.0",
   "description": "Omega-Level Development Kit - AI Team System for Claude Code. 41 agents, 160 commands, 161 skills, 69 workflows.",
   "keywords": [
     "claude-code",

package/plugin/registry.yaml

@@ -1,9 +1,9 @@
 # OMGKIT Component Registry
 # Single Source of Truth for Agents, Skills, Commands, Workflows, and MCPs
-# Version: 2.24.3
+# Version: 2.25.0
 # Updated: 2026-01-06
 
-version: "2.24.3"
+version: "2.25.0"
 
 # =============================================================================
 # OPTIMIZED ALIGNMENT PRINCIPLE (OAP)

package/templates/settings.json

@@ -1,4 +1,10 @@
 {
+  "omgkit": {
+    "version": "{{OMGKIT_VERSION}}",
+    "initialized_at": "{{INIT_DATE}}",
+    "last_upgraded": null
+  },
+  "file_checksums": {},
   "permissions": {
     "allow": [
       "Bash(npm run *)",