@mindfoldhq/trellis 0.1.9 → 0.2.2

package/dist/commands/update.js

@@ -4,18 +4,21 @@ import chalk from "chalk";
 import inquirer from "inquirer";
 import { PATHS, DIR_NAMES } from "../constants/paths.js";
 import { VERSION, PACKAGE_NAME } from "../cli/index.js";
+import { getMigrationsForVersion } from "../migrations/index.js";
+import { loadHashes, saveHashes, updateHashes, isTemplateModified, removeHash, renameHash, computeHash, } from "../utils/template-hash.js";
 // Import templates for comparison
-import { commonPathsScript, commonDeveloperScript, commonGitContextScript, commonWorktreeScript, multiAgentStartScript, multiAgentCleanupScript, multiAgentStatusScript, worktreeYamlTemplate, workflowMdTemplate, gitignoreTemplate, initDeveloperScript, getDeveloperScript, featureScript, getContextScript, addSessionScript, createBootstrapScript, } from "../templates/trellis/index.js";
+import { commonPathsScript, commonDeveloperScript, commonGitContextScript, commonWorktreeScript, commonTaskQueueScript, commonTaskUtilsScript, commonPhaseScript, commonRegistryScript, multiAgentStartScript, multiAgentCleanupScript, multiAgentStatusScript, multiAgentCreatePrScript, multiAgentPlanScript, worktreeYamlTemplate, workflowMdTemplate, gitignoreTemplate, initDeveloperScript, getDeveloperScript, taskScript, getContextScript, addSessionScript, createBootstrapScript, } from "../templates/trellis/index.js";
 import { guidesIndexContent, guidesCrossLayerThinkingGuideContent, guidesCodeReuseThinkingGuideContent, } from "../templates/markdown/index.js";
 import { getCommandTemplates } from "../configurators/templates.js";
 import { getAllAgents, getAllHooks, getSettingsTemplate, } from "../templates/claude/index.js";
 // Paths that should never be touched
 const PROTECTED_PATHS = [
-    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.PROGRESS}`, // agent-traces/
+    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.WORKSPACE}`, // workspace/
+    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.TASKS}`, // tasks/
     `${DIR_NAMES.WORKFLOW}/.developer`,
-    `${DIR_NAMES.WORKFLOW}/.current-feature`,
-    `${PATHS.STRUCTURE}/frontend`,
-    `${PATHS.STRUCTURE}/backend`,
+    `${DIR_NAMES.WORKFLOW}/.current-task`,
+    `${PATHS.SPEC}/frontend`,
+    `${PATHS.SPEC}/backend`,
 ];
 /**
  * Collect all template files that should be managed by update
@@ -27,14 +30,20 @@ function collectTemplateFiles(_cwd) {
     files.set(`${PATHS.SCRIPTS}/common/developer.sh`, commonDeveloperScript);
     files.set(`${PATHS.SCRIPTS}/common/git-context.sh`, commonGitContextScript);
     files.set(`${PATHS.SCRIPTS}/common/worktree.sh`, commonWorktreeScript);
+    files.set(`${PATHS.SCRIPTS}/common/task-queue.sh`, commonTaskQueueScript);
+    files.set(`${PATHS.SCRIPTS}/common/task-utils.sh`, commonTaskUtilsScript);
+    files.set(`${PATHS.SCRIPTS}/common/phase.sh`, commonPhaseScript);
+    files.set(`${PATHS.SCRIPTS}/common/registry.sh`, commonRegistryScript);
     // Scripts - multi-agent
     files.set(`${PATHS.SCRIPTS}/multi-agent/start.sh`, multiAgentStartScript);
     files.set(`${PATHS.SCRIPTS}/multi-agent/cleanup.sh`, multiAgentCleanupScript);
     files.set(`${PATHS.SCRIPTS}/multi-agent/status.sh`, multiAgentStatusScript);
+    files.set(`${PATHS.SCRIPTS}/multi-agent/create-pr.sh`, multiAgentCreatePrScript);
+    files.set(`${PATHS.SCRIPTS}/multi-agent/plan.sh`, multiAgentPlanScript);
     // Scripts - main
     files.set(`${PATHS.SCRIPTS}/init-developer.sh`, initDeveloperScript);
     files.set(`${PATHS.SCRIPTS}/get-developer.sh`, getDeveloperScript);
-    files.set(`${PATHS.SCRIPTS}/feature.sh`, featureScript);
+    files.set(`${PATHS.SCRIPTS}/task.sh`, taskScript);
     files.set(`${PATHS.SCRIPTS}/get-context.sh`, getContextScript);
     files.set(`${PATHS.SCRIPTS}/add-session.sh`, addSessionScript);
     files.set(`${PATHS.SCRIPTS}/create-bootstrap.sh`, createBootstrapScript);
@@ -42,10 +51,10 @@ function collectTemplateFiles(_cwd) {
     files.set(`${DIR_NAMES.WORKFLOW}/worktree.yaml`, worktreeYamlTemplate);
     files.set(`${DIR_NAMES.WORKFLOW}/.gitignore`, gitignoreTemplate);
     files.set(PATHS.WORKFLOW_GUIDE_FILE, workflowMdTemplate);
-    // Structure - guides only (frontend/backend are protected)
-    files.set(`${PATHS.STRUCTURE}/guides/index.md`, guidesIndexContent);
-    files.set(`${PATHS.STRUCTURE}/guides/cross-layer-thinking-guide.md`, guidesCrossLayerThinkingGuideContent);
-    files.set(`${PATHS.STRUCTURE}/guides/code-reuse-thinking-guide.md`, guidesCodeReuseThinkingGuideContent);
+    // Spec - guides only (frontend/backend are protected)
+    files.set(`${PATHS.SPEC}/guides/index.md`, guidesIndexContent);
+    files.set(`${PATHS.SPEC}/guides/cross-layer-thinking-guide.md`, guidesCrossLayerThinkingGuideContent);
+    files.set(`${PATHS.SPEC}/guides/code-reuse-thinking-guide.md`, guidesCodeReuseThinkingGuideContent);
     // Claude commands
     const claudeCommands = getCommandTemplates("claude-code");
     for (const [name, content] of Object.entries(claudeCommands)) {
@@ -73,12 +82,17 @@ function collectTemplateFiles(_cwd) {
 }
 /**
  * Analyze changes between current files and templates
+ *
+ * Uses hash tracking to distinguish between:
+ * - User didn't modify + template same = skip (unchangedFiles)
+ * - User didn't modify + template updated = auto-update (autoUpdateFiles)
+ * - User modified = needs confirmation (changedFiles)
  */
-function analyzeChanges(cwd) {
-    const templates = collectTemplateFiles(cwd);
+function analyzeChanges(cwd, hashes, templates) {
     const result = {
         newFiles: [],
         unchangedFiles: [],
+        autoUpdateFiles: [],
         changedFiles: [],
         protectedPaths: PROTECTED_PATHS,
     };
@@ -98,12 +112,26 @@ function analyzeChanges(cwd) {
         else {
             const existingContent = fs.readFileSync(fullPath, "utf-8");
             if (existingContent === newContent) {
+                // Content same as template - already up to date
                 change.status = "unchanged";
                 result.unchangedFiles.push(change);
             }
             else {
-                change.status = "changed";
-                result.changedFiles.push(change);
+                // Content differs - check if user modified or template updated
+                const storedHash = hashes[relativePath];
+                const currentHash = computeHash(existingContent);
+                if (storedHash && storedHash === currentHash) {
+                    // Hash matches stored hash - user didn't modify, template was updated
+                    // Safe to auto-update
+                    change.status = "changed";
+                    result.autoUpdateFiles.push(change);
+                }
+                else {
+                    // Hash differs (or no stored hash) - user modified the file
+                    // Needs confirmation
+                    change.status = "changed";
+                    result.changedFiles.push(change);
+                }
             }
         }
     }
@@ -121,6 +149,13 @@ function printChangeSummary(changes) {
         }
         console.log("");
     }
+    if (changes.autoUpdateFiles.length > 0) {
+        console.log(chalk.cyan("  Template updated (will auto-update):"));
+        for (const file of changes.autoUpdateFiles) {
+            console.log(chalk.cyan(`    ↑ ${file.relativePath}`));
+        }
+        console.log("");
+    }
     if (changes.unchangedFiles.length > 0) {
         console.log(chalk.gray("  Unchanged files (will skip):"));
         for (const file of changes.unchangedFiles.slice(0, 5)) {
@@ -132,17 +167,24 @@ function printChangeSummary(changes) {
         console.log("");
     }
     if (changes.changedFiles.length > 0) {
-        console.log(chalk.yellow("  Changed files (need your decision):"));
+        console.log(chalk.yellow("  Modified by you (need your decision):"));
         for (const file of changes.changedFiles) {
             console.log(chalk.yellow(`    ? ${file.relativePath}`));
         }
         console.log("");
     }
-    console.log(chalk.gray("  Protected (never touched):"));
-    for (const protectedPath of changes.protectedPaths) {
-        console.log(chalk.gray(`    ○ ${protectedPath}/`));
+    // Only show protected paths that actually exist
+    const existingProtectedPaths = changes.protectedPaths.filter((p) => {
+        const fullPath = path.join(process.cwd(), p);
+        return fs.existsSync(fullPath);
+    });
+    if (existingProtectedPaths.length > 0) {
+        console.log(chalk.gray("  User data (preserved):"));
+        for (const protectedPath of existingProtectedPaths) {
+            console.log(chalk.gray(`    ○ ${protectedPath}/`));
+        }
+        console.log("");
     }
-    console.log("");
 }
 /**
  * Prompt user for conflict resolution
@@ -200,26 +242,88 @@ async function promptConflictResolution(file, options, applyToAll) {
     return action;
 }
 /**
- * Create backup of files that will be changed
+ * Create a timestamped backup directory path
  */
-function createBackup(cwd, changes) {
-    const filesToBackup = changes.changedFiles;
-    if (filesToBackup.length === 0) {
-        return null;
-    }
+function createBackupDirPath(cwd) {
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-    const backupDir = path.join(cwd, DIR_NAMES.WORKFLOW, `.backup-${timestamp}`);
-    fs.mkdirSync(backupDir, { recursive: true });
-    for (const file of filesToBackup) {
-        if (fs.existsSync(file.path)) {
-            const relativePath = file.relativePath;
-            const backupPath = path.join(backupDir, relativePath);
-            const backupParent = path.dirname(backupPath);
-            fs.mkdirSync(backupParent, { recursive: true });
-            fs.copyFileSync(file.path, backupPath);
-        }
-    }
-    return backupDir;
+    return path.join(cwd, DIR_NAMES.WORKFLOW, `.backup-${timestamp}`);
+}
+/**
+ * Backup a single file to the backup directory
+ */
+function backupFile(cwd, backupDir, relativePath) {
+    const srcPath = path.join(cwd, relativePath);
+    if (!fs.existsSync(srcPath))
+        return;
+    const backupPath = path.join(backupDir, relativePath);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    fs.copyFileSync(srcPath, backupPath);
+}
+/**
+ * Backup an entire directory recursively
+ */
+function backupDirectory(cwd, backupDir, relativeDirPath) {
+    const srcDir = path.join(cwd, relativeDirPath);
+    if (!fs.existsSync(srcDir))
+        return;
+    const files = collectAllFiles(srcDir);
+    for (const fullPath of files) {
+        const relativePath = path.relative(cwd, fullPath);
+        backupFile(cwd, backupDir, relativePath);
+    }
+}
+/**
+ * Directories to backup as complete snapshot
+ */
+const BACKUP_DIRS = [".trellis", ".claude", ".cursor"];
+/**
+ * Patterns to exclude from backup (user data that shouldn't be backed up)
+ */
+const BACKUP_EXCLUDE_PATTERNS = [
+    ".backup-", // Previous backups
+    "/workspace/", // Developer workspace (user data)
+    "/tasks/", // Task data (user data)
+    "/backlog/", // Backlog data (user data)
+    "/agent-traces/", // Agent traces (user data, legacy name)
+];
+/**
+ * Check if a path should be excluded from backup
+ */
+function shouldExcludeFromBackup(relativePath) {
+    for (const pattern of BACKUP_EXCLUDE_PATTERNS) {
+        if (relativePath.includes(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Create complete snapshot backup of all managed directories
+ * Backs up .trellis, .claude, .cursor directories entirely
+ * (excluding user data like workspace/, tasks/, backlog/)
+ */
+function createFullBackup(cwd) {
+    const backupDir = createBackupDirPath(cwd);
+    let hasFiles = false;
+    for (const dir of BACKUP_DIRS) {
+        const dirPath = path.join(cwd, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        const files = collectAllFiles(dirPath);
+        for (const fullPath of files) {
+            const relativePath = path.relative(cwd, fullPath);
+            // Skip excluded paths
+            if (shouldExcludeFromBackup(relativePath))
+                continue;
+            // Create backup
+            if (!hasFiles) {
+                fs.mkdirSync(backupDir, { recursive: true });
+                hasFiles = true;
+            }
+            backupFile(cwd, backupDir, relativePath);
+        }
+    }
+    return hasFiles ? backupDir : null;
 }
 /**
  * Update version file
@@ -273,6 +377,447 @@ function compareVersions(a, b) {
     }
     return 0;
 }
+/**
+ * Recursively collect all files in a directory
+ */
+function collectAllFiles(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    const files = [];
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectAllFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+/**
+ * Check if a directory only contains unmodified template files
+ * Returns true if safe to delete:
+ * - All files are tracked and unmodified, OR
+ * - All files match current template content (even if not tracked)
+ */
+function isDirectorySafeToReplace(cwd, dirRelativePath, hashes, templates) {
+    const dirFullPath = path.join(cwd, dirRelativePath);
+    if (!fs.existsSync(dirFullPath))
+        return true;
+    const files = collectAllFiles(dirFullPath);
+    if (files.length === 0)
+        return true; // Empty directory is safe
+    for (const fullPath of files) {
+        const relativePath = path.relative(cwd, fullPath);
+        const storedHash = hashes[relativePath];
+        const templateContent = templates.get(relativePath);
+        // Check if file matches template content (handles untracked files)
+        if (templateContent) {
+            const currentContent = fs.readFileSync(fullPath, "utf-8");
+            if (currentContent === templateContent) {
+                // File matches template - safe
+                continue;
+            }
+        }
+        // Check if file is tracked and unmodified
+        if (storedHash && !isTemplateModified(cwd, relativePath, hashes)) {
+            // Tracked and unmodified - safe
+            continue;
+        }
+        // File is either user-created or user-modified - not safe
+        return false;
+    }
+    return true;
+}
+/**
+ * Recursively delete a directory
+ */
+function removeDirectoryRecursive(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return;
+    fs.rmSync(dirPath, { recursive: true, force: true });
+}
+/**
+ * Check if a file is safe to overwrite (matches template content)
+ */
+function isFileSafeToReplace(cwd, relativePath, templates) {
+    const fullPath = path.join(cwd, relativePath);
+    if (!fs.existsSync(fullPath))
+        return true;
+    const templateContent = templates.get(relativePath);
+    if (!templateContent)
+        return false; // Not a template file
+    const currentContent = fs.readFileSync(fullPath, "utf-8");
+    return currentContent === templateContent;
+}
+/**
+ * Classify migrations based on file state and user modifications
+ */
+function classifyMigrations(migrations, cwd, hashes, templates) {
+    const result = {
+        auto: [],
+        confirm: [],
+        conflict: [],
+        skip: [],
+    };
+    for (const item of migrations) {
+        const oldPath = path.join(cwd, item.from);
+        const oldExists = fs.existsSync(oldPath);
+        if (!oldExists) {
+            // Old file doesn't exist, nothing to migrate
+            result.skip.push(item);
+            continue;
+        }
+        if (item.type === "rename" && item.to) {
+            const newPath = path.join(cwd, item.to);
+            const newExists = fs.existsSync(newPath);
+            if (newExists) {
+                // Both exist - check if new file matches template (safe to overwrite)
+                if (isFileSafeToReplace(cwd, item.to, templates)) {
+                    // New file is just template content - safe to delete and rename
+                    result.auto.push(item);
+                }
+                else {
+                    // New file has user content - conflict
+                    result.conflict.push(item);
+                }
+            }
+            else if (isTemplateModified(cwd, item.from, hashes)) {
+                // User has modified the file - needs confirmation
+                result.confirm.push(item);
+            }
+            else {
+                // Unmodified template - safe to auto-migrate
+                result.auto.push(item);
+            }
+        }
+        else if (item.type === "rename-dir" && item.to) {
+            const newPath = path.join(cwd, item.to);
+            const newExists = fs.existsSync(newPath);
+            if (newExists) {
+                // Target exists - check if it only contains unmodified template files
+                if (isDirectorySafeToReplace(cwd, item.to, hashes, templates)) {
+                    // Safe to delete target and rename source
+                    result.auto.push(item);
+                }
+                else {
+                    // Target has user modifications - conflict
+                    result.conflict.push(item);
+                }
+            }
+            else {
+                // Directory rename - always auto (includes user files)
+                result.auto.push(item);
+            }
+        }
+        else if (item.type === "delete") {
+            if (isTemplateModified(cwd, item.from, hashes)) {
+                // User has modified - needs confirmation before delete
+                result.confirm.push(item);
+            }
+            else {
+                // Unmodified - safe to auto-delete
+                result.auto.push(item);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Print migration summary
+ */
+function printMigrationSummary(classified) {
+    const total = classified.auto.length +
+        classified.confirm.length +
+        classified.conflict.length +
+        classified.skip.length;
+    if (total === 0) {
+        console.log(chalk.gray("  No migrations to apply.\n"));
+        return;
+    }
+    if (classified.auto.length > 0) {
+        console.log(chalk.green("  ✓ Auto-migrate (unmodified):"));
+        for (const item of classified.auto) {
+            if (item.type === "rename") {
+                console.log(chalk.green(`    ${item.from} → ${item.to}`));
+            }
+            else if (item.type === "rename-dir") {
+                console.log(chalk.green(`    [dir] ${item.from}/ → ${item.to}/`));
+            }
+            else {
+                console.log(chalk.green(`    ✕ ${item.from}`));
+            }
+        }
+        console.log("");
+    }
+    if (classified.confirm.length > 0) {
+        console.log(chalk.yellow("  ⚠ Requires confirmation (modified by user):"));
+        for (const item of classified.confirm) {
+            if (item.type === "rename") {
+                console.log(chalk.yellow(`    ${item.from} → ${item.to}`));
+            }
+            else {
+                console.log(chalk.yellow(`    ✕ ${item.from}`));
+            }
+        }
+        console.log("");
+    }
+    if (classified.conflict.length > 0) {
+        console.log(chalk.red("  ⊘ Conflict (both old and new exist):"));
+        for (const item of classified.conflict) {
+            if (item.type === "rename-dir") {
+                console.log(chalk.red(`    [dir] ${item.from}/ ↔ ${item.to}/`));
+            }
+            else {
+                console.log(chalk.red(`    ${item.from} ↔ ${item.to}`));
+            }
+        }
+        console.log(chalk.gray("    → Resolve manually: merge or delete one, then re-run update"));
+        console.log("");
+    }
+    if (classified.skip.length > 0) {
+        console.log(chalk.gray("  ○ Skipping (old file not found):"));
+        for (const item of classified.skip.slice(0, 3)) {
+            console.log(chalk.gray(`    ${item.from}`));
+        }
+        if (classified.skip.length > 3) {
+            console.log(chalk.gray(`    ... and ${classified.skip.length - 3} more`));
+        }
+        console.log("");
+    }
+}
+/**
+ * Prompt user for migration action on a single item
+ */
+async function promptMigrationAction(item) {
+    const action = item.type === "rename" ? `${item.from} → ${item.to}` : `Delete ${item.from}`;
+    const { choice } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "choice",
+            message: `${action}\nThis file has been modified. What would you like to do?`,
+            choices: [
+                {
+                    name: item.type === "rename" ? "[r] Rename anyway" : "[d] Delete anyway",
+                    value: "rename",
+                },
+                {
+                    name: "[b] Backup original, then proceed",
+                    value: "backup-rename",
+                },
+                {
+                    name: "[s] Skip this migration",
+                    value: "skip",
+                },
+            ],
+            default: "skip",
+        },
+    ]);
+    return choice;
+}
+/**
+ * Clean up empty directories after file migration
+ * Recursively removes empty parent directories up to .trellis root
+ */
+function cleanupEmptyDirs(cwd, dirPath) {
+    const fullPath = path.join(cwd, dirPath);
+    // Safety: don't delete outside of expected directories
+    if (!dirPath.startsWith(".trellis/") && !dirPath.startsWith(".claude/") && !dirPath.startsWith(".cursor/")) {
+        return;
+    }
+    // Check if directory exists and is empty
+    if (!fs.existsSync(fullPath))
+        return;
+    try {
+        const stat = fs.statSync(fullPath);
+        if (!stat.isDirectory())
+            return;
+        const contents = fs.readdirSync(fullPath);
+        if (contents.length === 0) {
+            fs.rmdirSync(fullPath);
+            // Recursively check parent (but stop at root directories)
+            const parent = path.dirname(dirPath);
+            if (parent !== "." && parent !== dirPath && parent !== ".trellis" && parent !== ".claude" && parent !== ".cursor") {
+                cleanupEmptyDirs(cwd, parent);
+            }
+        }
+    }
+    catch {
+        // Ignore errors (permission issues, etc.)
+    }
+}
+/**
+ * Sort migrations for safe execution order
+ * - rename-dir with deeper paths first (to handle nested directories)
+ * - rename-dir before rename/delete
+ */
+function sortMigrationsForExecution(migrations) {
+    return [...migrations].sort((a, b) => {
+        // rename-dir should be sorted by path depth (deeper first)
+        if (a.type === "rename-dir" && b.type === "rename-dir") {
+            const aDepth = a.from.split("/").length;
+            const bDepth = b.from.split("/").length;
+            return bDepth - aDepth; // Deeper paths first
+        }
+        // rename-dir before rename/delete (directories first)
+        if (a.type === "rename-dir" && b.type !== "rename-dir")
+            return -1;
+        if (a.type !== "rename-dir" && b.type === "rename-dir")
+            return 1;
+        return 0;
+    });
+}
+/**
+ * Execute classified migrations
+ *
+ * @param options.force - Force migrate modified files without asking
+ * @param options.skipAll - Skip all modified files without asking
+ * If neither is set, prompts interactively for modified files
+ */
+async function executeMigrations(classified, cwd, options) {
+    const result = {
+        renamed: 0,
+        deleted: 0,
+        skipped: 0,
+        conflicts: classified.conflict.length,
+    };
+    // Sort migrations for safe execution order
+    const sortedAuto = sortMigrationsForExecution(classified.auto);
+    // 1. Execute auto migrations (unmodified files and directories)
+    for (const item of sortedAuto) {
+        if (item.type === "rename" && item.to) {
+            const oldPath = path.join(cwd, item.from);
+            const newPath = path.join(cwd, item.to);
+            // Ensure target directory exists
+            fs.mkdirSync(path.dirname(newPath), { recursive: true });
+            fs.renameSync(oldPath, newPath);
+            // Update hash tracking
+            renameHash(cwd, item.from, item.to);
+            // Make executable if it's a script
+            if (item.to.endsWith(".sh")) {
+                fs.chmodSync(newPath, "755");
+            }
+            // Clean up empty source directory
+            cleanupEmptyDirs(cwd, path.dirname(item.from));
+            result.renamed++;
+        }
+        else if (item.type === "rename-dir" && item.to) {
+            const oldPath = path.join(cwd, item.from);
+            const newPath = path.join(cwd, item.to);
+            // If target exists (safe to replace, already checked in classification)
+            // delete it first before renaming
+            if (fs.existsSync(newPath)) {
+                removeDirectoryRecursive(newPath);
+            }
+            // Ensure parent directory exists
+            fs.mkdirSync(path.dirname(newPath), { recursive: true });
+            // Rename the entire directory (includes all user files)
+            fs.renameSync(oldPath, newPath);
+            // Batch update hash tracking for all files in the directory
+            const hashes = loadHashes(cwd);
+            const oldPrefix = item.from.endsWith("/") ? item.from : item.from + "/";
+            const newPrefix = item.to.endsWith("/") ? item.to : item.to + "/";
+            const updatedHashes = {};
+            for (const [hashPath, hashValue] of Object.entries(hashes)) {
+                if (hashPath.startsWith(oldPrefix)) {
+                    // Rename path: old prefix -> new prefix
+                    const newHashPath = newPrefix + hashPath.slice(oldPrefix.length);
+                    updatedHashes[newHashPath] = hashValue;
+                }
+                else if (hashPath.startsWith(newPrefix)) {
+                    // Skip old hashes from deleted target directory
+                    // (they will be replaced by renamed source files)
+                    continue;
+                }
+                else {
+                    // Keep unchanged
+                    updatedHashes[hashPath] = hashValue;
+                }
+            }
+            saveHashes(cwd, updatedHashes);
+            result.renamed++;
+        }
+        else if (item.type === "delete") {
+            const filePath = path.join(cwd, item.from);
+            fs.unlinkSync(filePath);
+            // Remove from hash tracking
+            removeHash(cwd, item.from);
+            // Clean up empty directory
+            cleanupEmptyDirs(cwd, path.dirname(item.from));
+            result.deleted++;
+        }
+    }
+    // 2. Handle confirm items (modified files)
+    // Note: All files are already backed up by createMigrationBackup before execution
+    for (const item of classified.confirm) {
+        let action;
+        if (options.force) {
+            // Force mode: proceed (already backed up)
+            action = "rename";
+        }
+        else if (options.skipAll) {
+            // Skip mode: skip all modified files
+            action = "skip";
+        }
+        else {
+            // Default: interactive prompt
+            action = await promptMigrationAction(item);
+        }
+        if (action === "skip") {
+            result.skipped++;
+            continue;
+        }
+        // For backup-rename, just proceed (backup already done)
+        // Proceed with rename or delete
+        if (item.type === "rename" && item.to) {
+            const oldPath = path.join(cwd, item.from);
+            const newPath = path.join(cwd, item.to);
+            fs.mkdirSync(path.dirname(newPath), { recursive: true });
+            fs.renameSync(oldPath, newPath);
+            renameHash(cwd, item.from, item.to);
+            if (item.to.endsWith(".sh")) {
+                fs.chmodSync(newPath, "755");
+            }
+            // Clean up empty source directory
+            cleanupEmptyDirs(cwd, path.dirname(item.from));
+            result.renamed++;
+        }
+        else if (item.type === "delete") {
+            const filePath = path.join(cwd, item.from);
+            fs.unlinkSync(filePath);
+            removeHash(cwd, item.from);
+            // Clean up empty directory
+            cleanupEmptyDirs(cwd, path.dirname(item.from));
+            result.deleted++;
+        }
+    }
+    // 3. Skip count already tracked (old files not found)
+    result.skipped += classified.skip.length;
+    return result;
+}
+/**
+ * Print migration result summary
+ */
+function printMigrationResult(result) {
+    const parts = [];
+    if (result.renamed > 0) {
+        parts.push(`${result.renamed} renamed`);
+    }
+    if (result.deleted > 0) {
+        parts.push(`${result.deleted} deleted`);
+    }
+    if (result.skipped > 0) {
+        parts.push(`${result.skipped} skipped`);
+    }
+    if (result.conflicts > 0) {
+        parts.push(`${result.conflicts} conflict${result.conflicts > 1 ? "s" : ""}`);
+    }
+    if (parts.length > 0) {
+        console.log(chalk.cyan(`Migration complete: ${parts.join(", ")}`));
+    }
+}
 /**
  * Main update command
  */
@@ -322,15 +867,65 @@ export async function update(options) {
         }
         console.log(chalk.yellow("⚠️  --allow-downgrade flag set. Proceeding with downgrade...\n"));
     }
-    // Analyze changes
-    const changes = analyzeChanges(cwd);
+    // Load template hashes for modification detection
+    const hashes = loadHashes(cwd);
+    const isFirstHashTracking = Object.keys(hashes).length === 0;
+    // Handle unknown version - skip migrations but continue with template updates
+    const isUnknownVersion = projectVersion === "unknown";
+    if (isUnknownVersion) {
+        console.log(chalk.yellow("⚠️  No version file found. Skipping migrations."));
+        console.log(chalk.gray("   Template updates will still be applied."));
+        console.log(chalk.gray("   If your project used old file paths, you may need to rename them manually.\n"));
+    }
+    // Collect templates (used for both migration classification and change analysis)
+    const templates = collectTemplateFiles(cwd);
+    // Check for pending migrations (skip if unknown version)
+    const pendingMigrations = isUnknownVersion
+        ? []
+        : getMigrationsForVersion(projectVersion, cliVersion);
+    const hasMigrations = pendingMigrations.length > 0;
+    // Classify migrations (stored for later backup creation)
+    let classifiedMigrations = null;
+    if (hasMigrations) {
+        console.log(chalk.cyan("Analyzing migrations...\n"));
+        classifiedMigrations = classifyMigrations(pendingMigrations, cwd, hashes, templates);
+        printMigrationSummary(classifiedMigrations);
+        // Show hint about --migrate flag (execution happens later after backup)
+        if (!options.migrate) {
+            const autoCount = classifiedMigrations.auto.length;
+            const confirmCount = classifiedMigrations.confirm.length;
+            if (autoCount > 0 || confirmCount > 0) {
+                console.log(chalk.gray(`Tip: Use --migrate to apply migrations (prompts for modified files).`));
+                if (confirmCount > 0) {
+                    console.log(chalk.gray(`     Use --migrate -f to force all, or --migrate -s to skip modified.\n`));
+                }
+                else {
+                    console.log("");
+                }
+            }
+        }
+    }
+    // Analyze changes (pass hashes for modification detection)
+    const changes = analyzeChanges(cwd, hashes, templates);
     // Print summary
     printChangeSummary(changes);
+    // First-time hash tracking hint
+    if (isFirstHashTracking && changes.changedFiles.length > 0) {
+        console.log(chalk.cyan("ℹ️  First update with hash tracking enabled."));
+        console.log(chalk.gray("   Changed files shown above may not be actual user modifications."));
+        console.log(chalk.gray("   After this update, hash tracking will accurately detect changes.\n"));
+    }
     // Check if there's anything to do
     const isUpgrade = cliVsProject > 0;
     const isDowngrade = cliVsProject < 0;
     const isSameVersion = cliVsProject === 0;
-    if (changes.newFiles.length === 0 && changes.changedFiles.length === 0) {
+    // Check if we have pending migrations that need to be applied
+    const hasPendingMigrations = options.migrate && classifiedMigrations && (classifiedMigrations.auto.length > 0 ||
+        classifiedMigrations.confirm.length > 0);
+    if (changes.newFiles.length === 0 &&
+        changes.autoUpdateFiles.length === 0 &&
+        changes.changedFiles.length === 0 &&
+        !hasPendingMigrations) {
         if (isSameVersion) {
             console.log(chalk.green("✓ Already up to date!"));
         }
@@ -364,10 +959,19 @@ export async function update(options) {
         console.log(chalk.yellow("Update cancelled."));
         return;
     }
-    // Create backup if needed
-    const backupDir = createBackup(cwd, changes);
+    // Create complete backup of .trellis, .claude, .cursor directories
+    const backupDir = createFullBackup(cwd);
+    if (backupDir) {
+        console.log(chalk.gray(`\nBackup created: ${path.relative(cwd, backupDir)}/`));
+    }
+    // Execute migrations if --migrate flag is set
+    if (options.migrate && classifiedMigrations) {
+        const migrationResult = await executeMigrations(classifiedMigrations, cwd, { force: options.force, skipAll: options.skipAll });
+        printMigrationResult(migrationResult);
+    }
     // Track results
     let added = 0;
+    let autoUpdated = 0;
     let updated = 0;
     let skipped = 0;
     let createdNew = 0;
@@ -386,6 +990,19 @@ export async function update(options) {
             added++;
         }
     }
+    // Auto-update files (template updated, user didn't modify)
+    if (changes.autoUpdateFiles.length > 0) {
+        console.log(chalk.blue("\nAuto-updating template files..."));
+        for (const file of changes.autoUpdateFiles) {
+            fs.writeFileSync(file.path, file.newContent);
+            // Make scripts executable
+            if (file.relativePath.endsWith(".sh")) {
+                fs.chmodSync(file.path, "755");
+            }
+            console.log(chalk.cyan(`  ↑ ${file.relativePath}`));
+            autoUpdated++;
+        }
+    }
     // Handle changed files
     if (changes.changedFiles.length > 0) {
         console.log(chalk.blue("\n--- Resolving conflicts ---\n"));
@@ -414,11 +1031,36 @@ export async function update(options) {
     }
     // Update version file
     updateVersionFile(cwd);
+    // Update template hashes for new, auto-updated, and overwritten files
+    const filesToHash = new Map();
+    for (const file of changes.newFiles) {
+        filesToHash.set(file.relativePath, file.newContent);
+    }
+    // Auto-updated files always get new hash
+    for (const file of changes.autoUpdateFiles) {
+        filesToHash.set(file.relativePath, file.newContent);
+    }
+    // Only hash overwritten files (not skipped or .new copies)
+    for (const file of changes.changedFiles) {
+        const fullPath = path.join(cwd, file.relativePath);
+        if (fs.existsSync(fullPath)) {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            if (content === file.newContent) {
+                filesToHash.set(file.relativePath, file.newContent);
+            }
+        }
+    }
+    if (filesToHash.size > 0) {
+        updateHashes(cwd, filesToHash);
+    }
     // Print summary
     console.log(chalk.cyan("\n--- Summary ---\n"));
     if (added > 0) {
         console.log(`  Added: ${added} file(s)`);
     }
+    if (autoUpdated > 0) {
+        console.log(`  Auto-updated: ${autoUpdated} file(s)`);
+    }
     if (updated > 0) {
         console.log(`  Updated: ${updated} file(s)`);
     }