@pennixrv/trellis 0.6.17

package/dist/commands/update.js

@@ -0,0 +1,2163 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
+import { VERSION, PACKAGE_NAME } from "../constants/version.js";
+import { getMigrationsForVersion, getAllMigrations, getMigrationMetadata, getConfigSectionsAddedBetween, } from "../migrations/index.js";
+import { loadHashes, saveHashes, updateHashes, isTemplateModified, removeHash, renameHash, computeHash, shouldExcludeFromHash, } from "../utils/template-hash.js";
+import { compareVersions } from "../utils/compare-versions.js";
+import { toPosix } from "../utils/posix.js";
+import { setupProxy } from "../utils/proxy.js";
+import { emptyTaskJson } from "../utils/task-json.js";
+// Import templates for comparison
+import { getAllScripts, getAllAgents, 
+// Configuration
+configYamlTemplate, gitignoreTemplate, workflowMdTemplate, } from "../templates/trellis/index.js";
+import { agentsMdContent } from "../templates/markdown/index.js";
+import { COPILOT_INSTRUCTIONS_BLOCK_END, COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_PATH, getCopilotInstructions, } from "../templates/copilot/index.js";
+import { ALL_MANAGED_DIRS, getConfiguredPlatforms, collectPlatformTemplates, } from "../configurators/index.js";
+import { replacePythonCommandLiterals } from "../configurators/shared.js";
+import { preserveCodexAgentModelKeys } from "../configurators/codex.js";
+import { printZcodeSetupHint } from "../configurators/zcode.js";
+import { ensureGitattributes } from "../configurators/workflow.js";
+import { pruneOrphanManifestKeys } from "../utils/manifest-prune.js";
+import { fetchRegistrySpecTemplates, collectDirectoryFiles, removeDirectory, parseRegistrySource, probeRegistryIndex, downloadTemplateById, } from "../utils/template-fetcher.js";
+import { loadSpecRegistryConfig } from "../utils/registry-config.js";
+import { cleanupEmptyDirs, TRELLIS_BLOCK_END, TRELLIS_BLOCK_START, } from "../utils/managed-paths.js";
+export { cleanupEmptyDirs, TRELLIS_BLOCK_END, TRELLIS_BLOCK_START, } from "../utils/managed-paths.js";
+const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+const LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES = new Set([
+    // v0.5.0-beta.17 and earlier wrote AGENTS.md but did not hash-track it.
+    // This hash is the pristine Trellis-managed block before the Subagents
+    // section was added, so old untouched projects can be updated without a
+    // false "modified by you" conflict.
+    "c1f511b1cfc1902f2147da159f09cc51f380b0c9e341cdb3ac5dea5233f3e307",
+]);
+// Paths that should never be touched (true user data)
+// spec/ is user-customized content created during init; update should never modify it
+const PROTECTED_PATHS = [
+    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.WORKSPACE}`, // workspace/
+    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.TASKS}`, // tasks/
+    `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.SPEC}`, // spec/
+    `${DIR_NAMES.WORKFLOW}/.developer`,
+    `${DIR_NAMES.WORKFLOW}/.current-task`,
+];
+function getManagedBlock(content, startMarker, endMarker) {
+    const start = content.indexOf(startMarker);
+    if (start === -1) {
+        return null;
+    }
+    const end = content.indexOf(endMarker, start);
+    if (end === -1) {
+        return null;
+    }
+    return content.slice(start, end + endMarker.length);
+}
+function getTrellisManagedBlock(content) {
+    return getManagedBlock(content, TRELLIS_BLOCK_START, TRELLIS_BLOCK_END);
+}
+function replaceManagedBlock(existingContent, templateContent, startMarker, endMarker) {
+    const existingStart = existingContent.indexOf(startMarker);
+    if (existingStart === -1) {
+        return null;
+    }
+    const existingEnd = existingContent.indexOf(endMarker, existingStart);
+    if (existingEnd === -1) {
+        return null;
+    }
+    const templateBlock = getManagedBlock(templateContent, startMarker, endMarker);
+    if (!templateBlock) {
+        return null;
+    }
+    return (existingContent.slice(0, existingStart) +
+        templateBlock +
+        existingContent.slice(existingEnd + endMarker.length));
+}
+function mergeManagedBlockContent(existingContent, templateContent, startMarker, endMarker) {
+    const replaced = replaceManagedBlock(existingContent, templateContent, startMarker, endMarker);
+    if (replaced !== null) {
+        return replaced;
+    }
+    const templateBlock = getManagedBlock(templateContent, startMarker, endMarker);
+    if (!templateBlock) {
+        return templateContent;
+    }
+    const trimmed = existingContent.replace(/\s+$/, "");
+    return `${trimmed}\n\n${templateBlock}\n`;
+}
+function buildManagedBlockTemplate(cwd, relativePath, templateContent, startMarker, endMarker) {
+    const fullPath = path.join(cwd, ...relativePath.split("/"));
+    if (!fs.existsSync(fullPath)) {
+        return templateContent;
+    }
+    const existingContent = fs.readFileSync(fullPath, "utf-8");
+    return mergeManagedBlockContent(existingContent, templateContent, startMarker, endMarker);
+}
+function buildAgentsMdTemplate(cwd) {
+    return buildManagedBlockTemplate(cwd, FILE_NAMES.AGENTS, agentsMdContent, TRELLIS_BLOCK_START, TRELLIS_BLOCK_END);
+}
+function buildCopilotInstructionsTemplate(cwd) {
+    return buildManagedBlockTemplate(cwd, COPILOT_INSTRUCTIONS_PATH, getCopilotInstructions(), COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_BLOCK_END);
+}
+function isKnownUntrackedTemplate(relativePath, existingContent) {
+    if (relativePath !== FILE_NAMES.AGENTS) {
+        return false;
+    }
+    const managedBlock = getTrellisManagedBlock(existingContent);
+    if (!managedBlock) {
+        return false;
+    }
+    return LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES.has(computeHash(managedBlock));
+}
+function isSafeUntrackedCopilotInstructionsMerge(relativePath, existingContent, newContent) {
+    if (relativePath !== COPILOT_INSTRUCTIONS_PATH) {
+        return false;
+    }
+    if (getManagedBlock(existingContent, COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_BLOCK_END)) {
+        return false;
+    }
+    return (mergeManagedBlockContent(existingContent, getCopilotInstructions(), COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_BLOCK_END) === newContent);
+}
+/**
+ * Check if a path is blocked by PROTECTED_PATHS
+ */
+function isProtectedPath(filePath) {
+    return PROTECTED_PATHS.some((pp) => filePath === pp || filePath.startsWith(pp.endsWith("/") ? pp : pp + "/"));
+}
+/**
+ * Collect and classify safe-file-delete migrations
+ *
+ * safe-file-delete auto-executes (no --migrate needed) when:
+ * - File exists
+ * - Content hash matches allowed_hashes
+ * - Path is not protected or in update.skip
+ * - Path is not owned by the current template set
+ */
+function collectSafeFileDeletes(migrations, cwd, skipPaths, currentTemplatePaths, 
+/**
+ * Bypass `update.skip` for safe-file-delete. Enable this for breaking releases
+ * where honoring skip would leave the project half-migrated (old files at
+ * protected paths sitting next to the new architecture forever). The hash
+ * check in `allowed_hashes` is still the ultimate safety net — user-modified
+ * files still stay put with a "skip-modified" warning.
+ */
+bypassUpdateSkip = false) {
+    // Historical migrations are loaded forever, so current template ownership
+    // must win when a later release intentionally restores a retired path.
+    const safeDeletes = migrations.filter((m) => m.type === "safe-file-delete" && !currentTemplatePaths.has(m.from));
+    const results = [];
+    for (const item of safeDeletes) {
+        const fullPath = path.join(cwd, item.from);
+        // Check: file exists?
+        if (!fs.existsSync(fullPath)) {
+            results.push({ item, action: "skip-missing" });
+            continue;
+        }
+        // Check: protected path? (user data dirs — always protected, never bypassed)
+        if (isProtectedPath(item.from)) {
+            results.push({ item, action: "skip-protected" });
+            continue;
+        }
+        // Check: update.skip? (can be bypassed for breaking releases)
+        if (!bypassUpdateSkip &&
+            skipPaths.some((skip) => item.from === skip ||
+                item.from.startsWith(skip.endsWith("/") ? skip : skip + "/"))) {
+            results.push({ item, action: "skip-update-skip" });
+            continue;
+        }
+        // Check: hash matches allowed_hashes?
+        if (!item.allowed_hashes || item.allowed_hashes.length === 0) {
+            // No allowed hashes defined — skip for safety
+            results.push({ item, action: "skip-modified" });
+            continue;
+        }
+        try {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            const fileHash = computeHash(content);
+            if (item.allowed_hashes.includes(fileHash)) {
+                results.push({ item, action: "delete" });
+            }
+            else {
+                results.push({ item, action: "skip-modified" });
+            }
+        }
+        catch {
+            results.push({ item, action: "skip-missing" });
+        }
+    }
+    return results;
+}
+/**
+ * Print safe-file-delete summary
+ */
+function printSafeFileDeleteSummary(classified) {
+    const toDelete = classified.filter((c) => c.action === "delete");
+    const modified = classified.filter((c) => c.action === "skip-modified");
+    const updateSkip = classified.filter((c) => c.action === "skip-update-skip");
+    if (toDelete.length === 0 &&
+        modified.length === 0 &&
+        updateSkip.length === 0) {
+        return;
+    }
+    console.log(chalk.cyan("  Deprecated commands cleanup:"));
+    if (toDelete.length > 0) {
+        for (const c of toDelete) {
+            console.log(chalk.green(`    ✕ ${c.item.from}${c.item.description ? ` (${c.item.description})` : ""}`));
+        }
+    }
+    if (modified.length > 0) {
+        for (const c of modified) {
+            console.log(chalk.yellow(`    ? ${c.item.from} (modified, skipped)`));
+        }
+    }
+    if (updateSkip.length > 0) {
+        for (const c of updateSkip) {
+            console.log(chalk.gray(`    ○ ${c.item.from} (skipped, update.skip)`));
+        }
+    }
+    console.log("");
+}
+/**
+ * Execute safe-file-delete items (delete files + clean up empty dirs)
+ */
+function executeSafeFileDeletes(classified, cwd) {
+    const toDelete = classified.filter((c) => c.action === "delete");
+    let deleted = 0;
+    for (const c of toDelete) {
+        const fullPath = path.join(cwd, c.item.from);
+        try {
+            fs.unlinkSync(fullPath);
+            removeHash(cwd, c.item.from);
+            cleanupEmptyDirs(cwd, path.dirname(c.item.from));
+            deleted++;
+        }
+        catch {
+            // File may have been removed between classify and execute
+        }
+    }
+    return deleted;
+}
+/**
+ * Load update.skip paths from .trellis/config.yaml
+ *
+ * Parses simple YAML structure:
+ *   update:
+ *     skip:
+ *       - path1
+ *       - path2
+ *
+ * @internal Exported for testing only
+ */
+export function loadUpdateSkipPaths(cwd) {
+    const configPath = path.join(cwd, DIR_NAMES.WORKFLOW, "config.yaml");
+    if (!fs.existsSync(configPath))
+        return [];
+    try {
+        const content = fs.readFileSync(configPath, "utf-8");
+        const lines = content.split("\n");
+        const paths = [];
+        let inUpdate = false;
+        let inSkip = false;
+        for (const line of lines) {
+            const trimmed = line.trimEnd();
+            // Check for "update:" section (no indentation or at root level)
+            if (/^update:\s*$/.test(trimmed)) {
+                inUpdate = true;
+                inSkip = false;
+                continue;
+            }
+            // Check for "skip:" under update (indented)
+            if (inUpdate && /^\s+skip:\s*$/.test(trimmed)) {
+                inSkip = true;
+                continue;
+            }
+            // Collect list items under skip
+            if (inSkip) {
+                const match = trimmed.match(/^\s+-\s+(.+)$/);
+                if (match) {
+                    paths.push(match[1].trim().replace(/^['"]|['"]$/g, ""));
+                    continue;
+                }
+                // If line is non-empty and not a list item, we've left the skip section
+                if (trimmed !== "" && !trimmed.startsWith("#")) {
+                    inSkip = false;
+                    inUpdate = false;
+                }
+            }
+            // If we're in update but hit a non-indented line, we've left the update section
+            if (inUpdate &&
+                trimmed !== "" &&
+                !trimmed.startsWith(" ") &&
+                !trimmed.startsWith("#")) {
+                inUpdate = false;
+                inSkip = false;
+            }
+        }
+        return paths;
+    }
+    catch {
+        // Config exists but failed to parse — warn user that skip rules won't apply
+        console.warn(`Warning: failed to parse ${configPath}, update.skip rules will not be applied`);
+        return [];
+    }
+}
+/**
+ * Extract a "section" from a config.yaml-style template by sectionHeading.
+ *
+ * A section is delimited by `#---...---` separator lines (the same pattern
+ * used in the bundled `config.yaml` template). The first line inside the
+ * separator block whose `# ` content matches `sectionHeading` identifies the
+ * section; the section spans from that opening separator block through the
+ * line preceding the next `#---` separator block (or EOF).
+ *
+ * Returns the extracted text including its leading separator block, or `null`
+ * when no matching section is found.
+ *
+ * @internal Exported for testing only.
+ */
+export function extractConfigSection(template, sectionHeading) {
+    const lines = template.split("\n");
+    const isSeparator = (line) => /^#-{3,}\s*$/.test(line.trimEnd());
+    for (let i = 0; i < lines.length; i++) {
+        if (!isSeparator(lines[i]))
+            continue;
+        // Look ahead for `# <heading>` then another separator that closes the
+        // heading block.
+        const headingLine = lines[i + 1];
+        const closingSeparator = lines[i + 2];
+        if (headingLine === undefined || closingSeparator === undefined)
+            continue;
+        if (!headingLine.startsWith("# "))
+            continue;
+        if (!isSeparator(closingSeparator))
+            continue;
+        if (headingLine.slice(2).trim() !== sectionHeading)
+            continue;
+        // Section starts at i; find the next separator block to bound it.
+        let end = lines.length;
+        for (let j = i + 3; j < lines.length; j++) {
+            if (isSeparator(lines[j])) {
+                end = j;
+                break;
+            }
+        }
+        return lines.slice(i, end).join("\n").replace(/\n+$/, "");
+    }
+    return null;
+}
+/**
+ * Apply additive config.yaml sections introduced between two versions.
+ *
+ * Walks the supplied entries, dedupes by `file+sentinel`, and for each unique
+ * entry: if the user file exists and lacks the sentinel, extracts the named
+ * section from `templateContent` and appends it. Idempotent — re-running the
+ * step on a file that already contains the sentinel is a no-op.
+ *
+ * @internal Exported for testing only.
+ */
+export function applyConfigSectionsAdded(entries, cwd, bundledTemplates) {
+    const seen = new Set();
+    let appended = 0;
+    for (const entry of entries) {
+        const dedupeKey = `${entry.file}::${entry.sentinel}`;
+        if (seen.has(dedupeKey))
+            continue;
+        seen.add(dedupeKey);
+        const targetPath = path.join(cwd, entry.file);
+        if (!fs.existsSync(targetPath))
+            continue;
+        let userContent;
+        try {
+            userContent = fs.readFileSync(targetPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        if (userContent.includes(entry.sentinel))
+            continue;
+        const template = bundledTemplates.get(entry.file);
+        if (!template)
+            continue;
+        const section = extractConfigSection(template, entry.sectionHeading);
+        if (!section)
+            continue;
+        const separator = userContent.endsWith("\n") ? "\n" : "\n\n";
+        const newContent = userContent + separator + section + "\n";
+        try {
+            fs.writeFileSync(targetPath, newContent);
+        }
+        catch {
+            continue;
+        }
+        console.log(chalk.green(`  + Added config section "${entry.sectionHeading}" to ${entry.file}`));
+        appended++;
+    }
+    return { appended };
+}
+/**
+ * Collect all template files that should be managed by update
+ * Only collects templates for platforms that are already configured (have directories)
+ */
+/**
+ * Detect if legacy Codex upgrade is needed.
+ *
+ * Old Trellis versions used `.agents/skills/` as codex's configDir.
+ * New versions use `.codex/` for Codex-specific config and `.agents/skills/`
+ * as a shared layer.
+ *
+ * Detection: Trellis-tracked hashes contain `.agents/skills/` entries
+ * but `.codex/` does not exist. This avoids misclassifying repos that
+ * have `.agents/skills/` from other tools (Kimi CLI, Amp, etc.).
+ *
+ * Returns true if upgrade is needed. Does NOT perform the upgrade —
+ * caller should run configurePlatform("codex") after backup/confirm.
+ */
+function needsCodexUpgrade(cwd) {
+    if (fs.existsSync(path.join(cwd, ".codex"))) {
+        return false;
+    }
+    // Legacy Codex marker: old Codex installs tracked command-as-skill files
+    // under `.agents/skills/` before `.codex/` existed as a separate config dir.
+    // A current or future non-Codex platform may own those paths too, so do not
+    // trigger the Codex backfill when a configured non-Codex platform declares
+    // the marker paths in its templates.
+    const hashes = loadHashes(cwd);
+    const legacyMarkers = [
+        ".agents/skills/trellis-continue/SKILL.md",
+        ".agents/skills/trellis-finish-work/SKILL.md",
+    ];
+    const hasLegacyMarker = legacyMarkers.some((key) => hashes[key] !== undefined);
+    if (!hasLegacyMarker) {
+        return false;
+    }
+    for (const platformId of getConfiguredPlatforms(cwd)) {
+        if (platformId === "codex") {
+            continue;
+        }
+        const platformFiles = collectPlatformTemplates(platformId);
+        if (platformFiles && legacyMarkers.some((key) => platformFiles.has(key))) {
+            return false;
+        }
+    }
+    return true;
+}
+function preserveExistingClaudeStatusLine(cwd, templates) {
+    const newSettingsContent = templates.get(CLAUDE_SETTINGS_PATH);
+    if (!newSettingsContent)
+        return;
+    const settingsPath = path.join(cwd, CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(settingsPath))
+        return;
+    try {
+        const existingSettings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        if (!Object.prototype.hasOwnProperty.call(existingSettings, "statusLine")) {
+            return;
+        }
+        const newSettings = JSON.parse(newSettingsContent);
+        if (Object.prototype.hasOwnProperty.call(newSettings, "statusLine")) {
+            return;
+        }
+        newSettings.statusLine = existingSettings.statusLine;
+        templates.set(CLAUDE_SETTINGS_PATH, `${JSON.stringify(newSettings, null, 2)}\n`);
+    }
+    catch {
+        // Invalid local JSON is handled by the normal conflict path.
+    }
+}
+function preserveExistingRegistryConfig(cwd, template) {
+    const registry = loadSpecRegistryConfig(cwd);
+    if (!registry)
+        return template;
+    return (template.trimEnd() +
+        "\n\n" +
+        "#-------------------------------------------------------------------------------\n" +
+        "# Registry\n" +
+        "#-------------------------------------------------------------------------------\n\n" +
+        "# Source used to install .trellis/spec. trellis update refreshes this\n" +
+        "# hash-tracked spec template while preserving local edits through the\n" +
+        "# normal update conflict flow.\n" +
+        "registry:\n" +
+        "  spec:\n" +
+        `    source: ${registry.source}\n` +
+        (registry.template ? `    template: ${registry.template}\n` : ""));
+}
+async function collectRegistrySpecTemplates(cwd) {
+    const config = loadSpecRegistryConfig(cwd);
+    if (!config)
+        return new Map();
+    let registry;
+    try {
+        registry = parseRegistrySource(config.source);
+    }
+    catch (error) {
+        console.log(chalk.yellow(`Warning: invalid registry.spec.source in .trellis/config.yaml: ${error instanceof Error ? error.message : String(error)}`));
+        return new Map();
+    }
+    const probe = await probeRegistryIndex(`${registry.rawBaseUrl}/index.json`, registry);
+    if (probe.templates.length > 0) {
+        if (!config.template) {
+            console.log(chalk.gray("Registry spec update skipped: marketplace registries require registry.spec.template."));
+            return new Map();
+        }
+        const template = probe.templates.find((candidate) => candidate.id === config.template);
+        if (!template) {
+            console.log(chalk.yellow(`Warning: registry spec update skipped: template "${config.template}" was not found in registry index.`));
+            return new Map();
+        }
+        const tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), "trellis-registry-template-"));
+        try {
+            const result = await downloadTemplateById(tempRoot, config.template, "overwrite", template, registry, undefined, probe.backend);
+            if (!result.success) {
+                console.log(chalk.yellow(`Warning: registry spec update skipped: ${result.message}`));
+                return new Map();
+            }
+            return collectDirectoryFiles(path.join(tempRoot, PATHS.SPEC), PATHS.SPEC);
+        }
+        finally {
+            await removeDirectory(tempRoot);
+        }
+    }
+    if (!probe.isNotFound) {
+        console.log(chalk.yellow(`Warning: registry spec update skipped: ${probe.error?.message ?? "could not reach registry"}`));
+        return new Map();
+    }
+    const result = await fetchRegistrySpecTemplates(registry, probe.backend);
+    if (!result.success) {
+        console.log(chalk.yellow(`Warning: registry spec update skipped: ${result.message ?? "download failed"}`));
+        return new Map();
+    }
+    return result.files;
+}
+async function collectTemplateFiles(cwd, extraPlatforms, 
+/**
+ * Bypass `update.skip` when collecting templates. Enable this for breaking
+ * releases so new files (e.g. `continue.md` added in 0.5.0) and template
+ * updates can land even under skip-protected paths. Without this, users with
+ * `.claude/commands/` in their skip list would silently miss new commands.
+ * Existing user customizations are still guarded at WRITE time via the
+ * "Modified by you" conflict prompt — they can skip per-file there.
+ */
+bypassUpdateSkip = false) {
+    const files = new Map();
+    const platforms = getConfiguredPlatforms(cwd);
+    if (extraPlatforms) {
+        for (const p of extraPlatforms) {
+            platforms.add(p);
+        }
+    }
+    // Python scripts (single source of truth: getAllScripts())
+    for (const [scriptPath, content] of getAllScripts()) {
+        files.set(`${PATHS.SCRIPTS}/${scriptPath}`, content);
+    }
+    // Channel runtime agent definitions (single source of truth: getAllAgents()).
+    // Backfilled by `trellis update` if missing so users who installed before the
+    // bundled agents existed pick them up. Edited files take the standard
+    // modified-file prompt path.
+    for (const [agentFile, content] of getAllAgents()) {
+        files.set(`${PATHS.AGENTS}/${agentFile}`, content);
+    }
+    // Configuration
+    files.set(`${DIR_NAMES.WORKFLOW}/config.yaml`, preserveExistingRegistryConfig(cwd, configYamlTemplate));
+    files.set(`${DIR_NAMES.WORKFLOW}/.gitignore`, gitignoreTemplate);
+    // workflow.md is included here because it is runtime-parsed by
+    // get_context.py and shared hooks. Keep it on the normal template update
+    // path: if the installed file still matches the tracked hash, update the
+    // whole file. If the user edited it, the standard modified-file prompt /
+    // --force behavior applies. Partial tag-block merging is unsafe because
+    // platform routing markers outside [workflow-state:*] blocks are also
+    // script-consumed.
+    files.set(`${DIR_NAMES.WORKFLOW}/workflow.md`, workflowMdTemplate);
+    // workspace/index.md stays excluded — it's runtime-appended by add_session.py
+    // (journal index) and has no script-parsed structure.
+    files.set(FILE_NAMES.AGENTS, buildAgentsMdTemplate(cwd));
+    // Platform-specific templates (only for configured platforms)
+    for (const platformId of platforms) {
+        const platformFiles = collectPlatformTemplates(platformId);
+        if (platformFiles) {
+            for (const [filePath, content] of platformFiles) {
+                files.set(filePath, content);
+            }
+            if (platformId === "copilot") {
+                files.set(COPILOT_INSTRUCTIONS_PATH, buildCopilotInstructionsTemplate(cwd));
+            }
+        }
+    }
+    // Users configure sub-agent models by editing `model` /
+    // `model_reasoning_effort` directly on the generated agent tomls. Preserve
+    // those two keys from the on-disk files into the freshly rendered desired
+    // content so a project whose only local edit is these keys is not flagged
+    // as a modified-file conflict by the hash comparison below.
+    if (platforms.has("codex")) {
+        preserveCodexAgentModelKeys(cwd, files);
+    }
+    preserveExistingClaudeStatusLine(cwd, files);
+    for (const [filePath, content] of await collectRegistrySpecTemplates(cwd)) {
+        files.set(filePath, content);
+    }
+    // Apply update.skip from config.yaml (unless bypassed for breaking release)
+    if (!bypassUpdateSkip) {
+        const skipPaths = loadUpdateSkipPaths(cwd);
+        if (skipPaths.length > 0) {
+            for (const [filePath] of [...files]) {
+                if (skipPaths.some((skip) => filePath === skip ||
+                    filePath.startsWith(skip.endsWith("/") ? skip : skip + "/"))) {
+                    files.delete(filePath);
+                }
+            }
+        }
+    }
+    // Apply python3→python replacement for Windows consistency with init-time writes
+    for (const [filePath, content] of files) {
+        files.set(filePath, replacePythonCommandLiterals(content));
+    }
+    return files;
+}
+/**
+ * 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, hashes, templates) {
+    const result = {
+        newFiles: [],
+        unchangedFiles: [],
+        autoUpdateFiles: [],
+        changedFiles: [],
+        userDeletedFiles: [],
+        protectedPaths: PROTECTED_PATHS,
+    };
+    for (const [relativePath, newContent] of templates) {
+        const fullPath = path.join(cwd, relativePath);
+        const exists = fs.existsSync(fullPath);
+        const change = {
+            path: fullPath,
+            relativePath,
+            newContent,
+            status: "new",
+        };
+        if (!exists) {
+            const storedHash = hashes[relativePath];
+            if (storedHash) {
+                // Previously installed but user deleted — respect deletion
+                result.userDeletedFiles.push(change);
+            }
+            else {
+                change.status = "new";
+                result.newFiles.push(change);
+            }
+        }
+        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 {
+                // Content differs - check if user modified or template updated
+                const storedHash = hashes[relativePath];
+                const currentHash = computeHash(existingContent);
+                if ((storedHash && storedHash === currentHash) ||
+                    (!storedHash &&
+                        isKnownUntrackedTemplate(relativePath, existingContent)) ||
+                    (!storedHash &&
+                        isSafeUntrackedCopilotInstructionsMerge(relativePath, existingContent, newContent))) {
+                    // Either the tracked hash matches, or this is a known pristine template
+                    // from before the path was hash-tracked. 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);
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Receipt entries that are wrong or missing for a file that is already
+ * byte-identical to its template.
+ *
+ * Nothing else repairs these. `analyzeChanges` classifies such a file
+ * `unchanged`, and the write-back draws only from `newFiles`,
+ * `autoUpdateFiles` and overwritten `changedFiles` — so a poisoned or absent
+ * entry beside a pristine file survives every subsequent `trellis update`,
+ * however many times it is run. Identical template content across versions is
+ * not what saves such an entry from going stale; it is precisely what freezes
+ * it, because the file never leaves the `unchanged` bucket.
+ *
+ * Recording the template's hash here cannot bless a local edit. Membership in
+ * `unchangedFiles` means the file on disk already *is* the template, byte for
+ * byte, so the value written is the one a correct receipt would already hold.
+ * A genuinely customized file differs from its template, lands in
+ * `changedFiles`, and is never seen by this function.
+ *
+ * That also leaves the mixed-ownership paths — `AGENTS.md`,
+ * `.github/copilot-instructions.md`, `.trellis/config.yaml` — free to differ
+ * from their recorded hash, which for them is the correct state: once the
+ * repository has appended its own content they are no longer `unchanged`.
+ */
+function collectUnchangedFileHashRepairs(changes, hashes) {
+    const files = new Map();
+    for (const file of changes.unchangedFiles) {
+        const key = toPosix(file.relativePath);
+        const recorded = hashes[key];
+        if (recorded === undefined) {
+            // A missing entry is only an omission for a path the receipt is meant
+            // to carry. `EXCLUDE_FROM_HASH` holds paths deliberately left out —
+            // `.trellis/.gitignore` among them — and adding those here would put
+            // this path in disagreement with `initializeHashes` about what the
+            // receipt tracks at all.
+            if (!shouldExcludeFromHash(key)) {
+                files.set(key, file.newContent);
+            }
+            continue;
+        }
+        // An entry that already exists and disagrees with the file is repaired
+        // whatever the path: a wrong value is strictly worse than an absent one,
+        // because it reads as a real local modification.
+        if (recorded !== computeHash(file.newContent)) {
+            files.set(key, file.newContent);
+        }
+    }
+    return files;
+}
+/**
+ * Print change summary
+ */
+function printChangeSummary(changes) {
+    console.log("\nScanning for changes...\n");
+    if (changes.newFiles.length > 0) {
+        console.log(chalk.green("  New files (will add):"));
+        for (const file of changes.newFiles) {
+            console.log(chalk.green(`    + ${file.relativePath}`));
+        }
+        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)) {
+            console.log(chalk.gray(`    ○ ${file.relativePath}`));
+        }
+        if (changes.unchangedFiles.length > 5) {
+            console.log(chalk.gray(`    ... and ${changes.unchangedFiles.length - 5} more`));
+        }
+        console.log("");
+    }
+    if (changes.changedFiles.length > 0) {
+        console.log(chalk.yellow("  Modified by you (need your decision):"));
+        for (const file of changes.changedFiles) {
+            console.log(chalk.yellow(`    ? ${file.relativePath}`));
+        }
+        console.log("");
+    }
+    if (changes.userDeletedFiles.length > 0) {
+        console.log(chalk.gray("  Deleted by you (preserved):"));
+        for (const file of changes.userDeletedFiles) {
+            console.log(chalk.gray(`    \u2715 ${file.relativePath}`));
+        }
+        console.log("");
+    }
+    // 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("");
+    }
+}
+/**
+ * Prompt user for conflict resolution
+ */
+async function promptConflictResolution(file, options, applyToAll) {
+    // If we have a batch action, use it
+    if (applyToAll.action) {
+        return applyToAll.action;
+    }
+    // Check command-line options
+    if (options.force) {
+        return "overwrite";
+    }
+    if (options.skipAll) {
+        return "skip";
+    }
+    if (options.createNew) {
+        return "create-new";
+    }
+    // Interactive prompt
+    const { action } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "action",
+            message: `${file.relativePath} has changes.`,
+            choices: [
+                {
+                    name: "[1] Overwrite - Replace with new version",
+                    value: "overwrite",
+                },
+                { name: "[2] Skip - Keep your current version", value: "skip" },
+                {
+                    name: "[3] Create copy - Save new version as .new",
+                    value: "create-new",
+                },
+                { name: "[a] Apply Overwrite to all", value: "overwrite-all" },
+                { name: "[s] Apply Skip to all", value: "skip-all" },
+                { name: "[n] Apply Create copy to all", value: "create-new-all" },
+            ],
+            default: "skip",
+        },
+    ]);
+    if (action === "overwrite-all") {
+        applyToAll.action = "overwrite";
+        return "overwrite";
+    }
+    if (action === "skip-all") {
+        applyToAll.action = "skip";
+        return "skip";
+    }
+    if (action === "create-new-all") {
+        applyToAll.action = "create-new";
+        return "create-new";
+    }
+    return action;
+}
+/**
+ * Create a timestamped backup directory path
+ */
+function createBackupDirPath(cwd) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    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);
+}
+/**
+ * Directories to backup as complete snapshot (derived from platform registry)
+ */
+const BACKUP_DIRS = ALL_MANAGED_DIRS;
+/** Root-level managed files to include in update backups. */
+const BACKUP_FILES = [FILE_NAMES.AGENTS];
+/**
+ * Patterns to exclude from backup (user data that shouldn't be backed up)
+ */
+const BACKUP_EXCLUDE_PATTERNS = [
+    ".backup-", // Previous backups
+    "/node_modules", // Installed dependencies; restore via package manager
+    "/workspace/", // Developer workspace (user data)
+    "/tasks/", // Task data (user data)
+    "/spec/", // Spec files (user-customized content)
+    "/backlog/", // Backlog data (user data)
+    "/agent-traces/", // Agent traces (user data, legacy name)
+    // Platform-native worktree dirs — these are full sub-repos the CLI
+    // spawns for parallel sessions. Backing them up on every update would
+    // snapshot the entire nested working tree. Confirmed conventions:
+    //   Claude Code: .claude/worktrees/
+    //   Cursor CLI:  .cursor/worktrees/
+    //   Gemini CLI:  .gemini/worktrees/
+    // Matches any platform using the same convention (future-proof).
+    "/worktrees/",
+    "/worktree/",
+];
+/**
+ * Check if a path should be excluded from backup
+ * @internal Exported for testing only
+ */
+export function shouldExcludeFromBackup(relativePath) {
+    // Normalize Windows backslashes to forward slashes so patterns like
+    // "/worktrees/" / "/tasks/" match regardless of host OS. Without this,
+    // Windows `path.relative` returns `.claude\worktrees\...` and none of
+    // the slash-prefixed exclude patterns trigger — which causes
+    // `collectAllFiles` to descend into platform worktrees (full nested
+    // project copies) and explode the scan. Same normalization pattern
+    // used by `isManagedPath` in configurators/index.ts.
+    const normalized = relativePath.replace(/\\/g, "/");
+    for (const pattern of BACKUP_EXCLUDE_PATTERNS) {
+        if (normalized.includes(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Create complete snapshot backup of all managed directories
+ * Backs up all managed platform/workflow 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, cwd);
+        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);
+        }
+    }
+    for (const relativePath of BACKUP_FILES) {
+        const fullPath = path.join(cwd, relativePath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        if (shouldExcludeFromBackup(relativePath))
+            continue;
+        if (!hasFiles) {
+            fs.mkdirSync(backupDir, { recursive: true });
+            hasFiles = true;
+        }
+        backupFile(cwd, backupDir, relativePath);
+    }
+    return hasFiles ? backupDir : null;
+}
+/**
+ * Update version file
+ */
+function updateVersionFile(cwd) {
+    const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
+    fs.writeFileSync(versionPath, VERSION);
+}
+/**
+ * Get current installed version
+ */
+function getInstalledVersion(cwd) {
+    const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
+    if (fs.existsSync(versionPath)) {
+        return fs.readFileSync(versionPath, "utf-8").trim();
+    }
+    return "unknown";
+}
+/**
+ * Fetch latest version from npm registry
+ */
+async function getLatestNpmVersion() {
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`);
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        return data.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Recursively collect all files in a directory
+ */
+function collectAllFiles(dirPath, cwd = process.cwd()) {
+    if (!fs.existsSync(dirPath))
+        return [];
+    const rootStat = fs.statSync(dirPath);
+    if (rootStat.isFile()) {
+        return [dirPath];
+    }
+    if (!rootStat.isDirectory()) {
+        return [];
+    }
+    const files = [];
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const currentDir = stack.pop();
+        if (!currentDir)
+            continue;
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            const relativePath = path.relative(cwd, fullPath);
+            // Never follow symlinks / Windows directory junctions — a junction
+            // pointing at an ancestor would loop the scan forever. Node's
+            // `isSymbolicLink()` returns true for NTFS junctions since v12.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (!shouldExcludeFromBackup(relativePath)) {
+                    stack.push(fullPath);
+                }
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Whether every file under `dirRelativePath` byte-matches the CURRENT
+ * template content for its path. Stricter than {@link isDirectorySafeToReplace},
+ * which also accepts files that are merely unmodified relative to an old
+ * stored hash (i.e. stale-but-untouched). Used to decide the safe *direction*
+ * of a rename-dir merge when both source and target exist: if the target
+ * already holds canonical current-version bytes, the source (however it got
+ * there) must not be allowed to overwrite it with older/differently-flavored
+ * content (#447 — a legacy `.pi/skills/` copy rendered with the Pi-specific
+ * resolver must not clobber the shared, neutral `.agents/skills/` content
+ * Codex/Gemini already wrote).
+ */
+function dirMatchesCurrentTemplates(cwd, dirRelativePath, templates) {
+    const dirFullPath = path.join(cwd, dirRelativePath);
+    if (!fs.existsSync(dirFullPath))
+        return false;
+    const files = collectAllFiles(dirFullPath, cwd);
+    if (files.length === 0)
+        return false;
+    for (const fullPath of files) {
+        const relativePath = toPosix(path.relative(cwd, fullPath));
+        const templateContent = templates.get(relativePath);
+        if (templateContent === undefined)
+            return false;
+        if (fs.readFileSync(fullPath, "utf-8") !== templateContent)
+            return false;
+    }
+    return true;
+}
+/**
+ * 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, cwd);
+    if (files.length === 0)
+        return true; // Empty directory is safe
+    for (const fullPath of files) {
+        // POSIX-normalize: hashes/templates keys are persisted as POSIX, but
+        // `path.relative` returns OS-native separators (backslash on Windows).
+        const relativePath = toPosix(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
+ */
+/**
+ * Whether the manifest records any file under `dirRelativePath` — i.e. whether
+ * Trellis actually created this directory. Used to gate rename-dir migrations:
+ * a directory Trellis never wrote (e.g. a user's own `.windsurf/` editor
+ * config that merely shares a path with a retired Trellis platform dir) must
+ * not be auto-moved.
+ */
+export function dirHasManifestEntries(dirRelativePath, hashes) {
+    const prefix = dirRelativePath.endsWith("/")
+        ? dirRelativePath
+        : dirRelativePath + "/";
+    return Object.keys(hashes).some((key) => key === dirRelativePath || key.startsWith(prefix));
+}
+export function classifyMigrations(migrations, cwd, hashes, templates) {
+    const result = {
+        auto: [],
+        confirm: [],
+        conflict: [],
+        skip: [],
+    };
+    for (const item of migrations) {
+        // safe-file-delete handled separately (not via --migrate)
+        if (item.type === "safe-file-delete")
+            continue;
+        // Enforce PROTECTED_PATHS — never migrate FROM protected paths (prevents moving/deleting user data)
+        if (isProtectedPath(item.from)) {
+            result.skip.push(item);
+            continue;
+        }
+        // For non-rename types, also block writing TO protected paths
+        // rename/rename-dir are allowed to target protected paths (e.g., 0.2.0 renames into .trellis/workspace)
+        if (item.to &&
+            isProtectedPath(item.to) &&
+            item.type !== "rename" &&
+            item.type !== "rename-dir") {
+            result.skip.push(item);
+            continue;
+        }
+        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 if (dirHasManifestEntries(item.from, hashes)) {
+                // Trellis created this directory (the manifest tracks files under it),
+                // so the rename is ours to make.
+                result.auto.push(item);
+            }
+            else {
+                // Target absent and the source has no manifest record: this is very
+                // likely a user-owned directory that merely shares a path with a
+                // retired Trellis platform dir (e.g. a real `.windsurf/` editor
+                // config). Skipping avoids silently moving the user's data out from
+                // under their editor — even under --force, since skip never executes.
+                result.skip.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 (not found, protected, or not Trellis-owned):"));
+        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.
+ *
+ * Design notes:
+ * - Default is `backup-rename`: safest — preserves user's content as a .backup
+ *   alongside the rename, so Enter-to-continue never destroys work or leaves
+ *   stale paths behind.
+ * - "Skip" leaves a stale old path that won't be cleaned by later updates —
+ *   warn explicitly so users understand the consequence.
+ * - Show manifest description + why-flagged so users can make an informed
+ *   choice without needing to dig through the diff.
+ */
+async function promptMigrationAction(item) {
+    const headline = item.type === "rename"
+        ? `${chalk.cyan(item.from)} → ${chalk.green(item.to)}`
+        : `${chalk.red("Delete")} ${chalk.cyan(item.from)}`;
+    const description = item.description ?? "No description provided in manifest.";
+    // Actions with inline guidance so users see the trade-off per choice.
+    const renameLabel = item.type === "rename"
+        ? "[r] Rename anyway — use if the file is unchanged, or any edits are fine to move as-is"
+        : "[d] Delete anyway — use if you don't need this file (already migrated to replacement)";
+    const backupLabel = item.type === "rename"
+        ? "[b] Backup original, then proceed — SAFEST: writes <new-path>.backup with your current content, then renames"
+        : "[b] Backup original, then proceed — SAFEST: writes <path>.backup with your current content, then deletes";
+    const skipLabel = item.type === "rename"
+        ? "[s] Skip — leaves the old path in place (you'll see it flagged on future updates until cleaned up manually)"
+        : "[s] Skip — keeps the deprecated file (you'll see it flagged on future updates until cleaned up manually)";
+    // Prefer the per-migration `reason` (version-specific context authored in the
+    // manifest) over a generic fallback. Hardcoding version-specific hints here
+    // rots fast — every release gets a new set of edge cases.
+    const whyFlagged = item.reason
+        ? chalk.gray(item.reason
+            .split("\n")
+            .map((line) => `  ${line}`)
+            .join("\n"))
+        : chalk.gray(`  Why prompted: file content doesn't match the Trellis template hash\n` +
+            `  for this path — usually local customization. If unsure, pick [b].`);
+    const message = [
+        headline,
+        "",
+        chalk.bold("  What:") + " " + description,
+        whyFlagged,
+        "",
+        chalk.bold("  Choose:"),
+    ].join("\n");
+    const { choice } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "choice",
+            message,
+            choices: [
+                { name: backupLabel, value: "backup-rename" },
+                { name: renameLabel, value: "rename" },
+                { name: skipLabel, value: "skip" },
+            ],
+            default: "backup-rename",
+        },
+    ]);
+    return choice;
+}
+/**
+ * Sort migrations for safe execution order
+ * - rename-dir with deeper paths first (to handle nested directories)
+ * - rename-dir before rename/delete
+ */
+/** @internal Exported for testing only */
+export 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
+ */
+export async function executeMigrations(classified, cwd, options, templates) {
+    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") || item.to.endsWith(".py")) {
+                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);
+            const oldPrefix = item.from.endsWith("/") ? item.from : item.from + "/";
+            const newPrefix = item.to.endsWith("/") ? item.to : item.to + "/";
+            // Target already exists and already holds canonical, current-version
+            // content (e.g. Codex/Gemini already wrote the shared `.agents/skills/`
+            // root before Pi's legacy `.pi/skills/` copy gets retired). Renaming
+            // the source in would clobber good content with older/differently-
+            // flavored bytes, so just drop the now-redundant source instead (#447).
+            if (fs.existsSync(newPath) &&
+                dirMatchesCurrentTemplates(cwd, item.to, templates)) {
+                removeDirectoryRecursive(oldPath);
+                const hashes = loadHashes(cwd);
+                const updatedHashes = {};
+                for (const [hashPath, hashValue] of Object.entries(hashes)) {
+                    if (hashPath.startsWith(oldPrefix))
+                        continue; // source retired
+                    updatedHashes[hashPath] = hashValue;
+                }
+                saveHashes(cwd, updatedHashes);
+                result.deleted++;
+                continue;
+            }
+            // 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 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`, leave an inline .backup copy of the user's modified
+        // original next to the new location (for rename) or in place (for delete).
+        // This is in addition to the full project snapshot at .trellis/.backup-*/;
+        // the inline copy is more discoverable when the user wants to diff or merge
+        // their customizations against the new template.
+        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 });
+            if (action === "backup-rename") {
+                // Copy original alongside the new path before the rename overwrites nothing
+                // (target dir is guaranteed fresh since `conflict` is handled elsewhere).
+                fs.copyFileSync(oldPath, newPath + ".backup");
+            }
+            fs.renameSync(oldPath, newPath);
+            renameHash(cwd, item.from, item.to);
+            if (item.to.endsWith(".sh") || item.to.endsWith(".py")) {
+                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);
+            if (action === "backup-rename") {
+                // Keep a .backup copy in place before deletion so the user can recover
+                // inline without digging through .trellis/.backup-*/.
+                fs.copyFileSync(filePath, filePath + ".backup");
+            }
+            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(", ")}`));
+    }
+}
+/**
+ * One-time 0.2.0 migration: rename `traces-*.md` → `journal-*.md` in every
+ * developer workspace directory.
+ *
+ * Never overwrites an existing `journal-N.md`: a newer session may already
+ * have created it, and `.trellis/workspace/` is excluded from the update
+ * backup (see `BACKUP_EXCLUDE_PATTERNS`), so clobbering it would be
+ * unrecoverable data loss. Conflicting `traces-N.md` files are left in place
+ * and reported instead.
+ */
+export function renameTracesToJournal(workspaceDir) {
+    const skipped = [];
+    let renamed = 0;
+    if (!fs.existsSync(workspaceDir))
+        return { renamed, skipped };
+    for (const dev of fs.readdirSync(workspaceDir)) {
+        const devPath = path.join(workspaceDir, dev);
+        if (!fs.statSync(devPath).isDirectory())
+            continue;
+        for (const file of fs.readdirSync(devPath)) {
+            if (!(file.startsWith("traces-") && file.endsWith(".md")))
+                continue;
+            const oldPath = path.join(devPath, file);
+            const newPath = path.join(devPath, file.replace("traces-", "journal-"));
+            if (fs.existsSync(newPath)) {
+                skipped.push(oldPath);
+                continue;
+            }
+            fs.renameSync(oldPath, newPath);
+            renamed++;
+        }
+    }
+    return { renamed, skipped };
+}
+/**
+ * Main update command
+ */
+export async function update(options) {
+    const cwd = process.cwd();
+    // Check if Trellis is initialized
+    if (!fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW))) {
+        console.log(chalk.red("Error: Trellis not initialized in this directory."));
+        console.log(chalk.gray("Run 'trellis init' first."));
+        return;
+    }
+    console.log(chalk.cyan("\nTrellis Update"));
+    console.log(chalk.cyan("══════════════\n"));
+    // Set up proxy before any network calls (npm version check)
+    setupProxy();
+    // Get versions
+    const projectVersion = getInstalledVersion(cwd);
+    const cliVersion = VERSION;
+    const latestNpmVersion = await getLatestNpmVersion();
+    // Version comparison
+    const cliVsProject = compareVersions(cliVersion, projectVersion);
+    const cliVsNpm = latestNpmVersion
+        ? compareVersions(cliVersion, latestNpmVersion)
+        : 0;
+    // Display versions with context
+    console.log(`Project version: ${chalk.white(projectVersion)}`);
+    console.log(`CLI version:     ${chalk.white(cliVersion)}`);
+    if (latestNpmVersion) {
+        console.log(`Latest on npm:   ${chalk.white(latestNpmVersion)}`);
+    }
+    else {
+        console.log(chalk.gray("Latest on npm:   (unable to fetch)"));
+    }
+    console.log("");
+    // Check if CLI is outdated compared to npm
+    if (cliVsNpm < 0 && latestNpmVersion) {
+        console.log(chalk.yellow(`⚠️  Your CLI (${cliVersion}) is behind npm (${latestNpmVersion}).`));
+        console.log(chalk.yellow(`   Run: trellis upgrade\n`));
+    }
+    // Check for downgrade situation
+    if (cliVsProject < 0) {
+        console.log(chalk.red(`❌ Cannot update: CLI version (${cliVersion}) < project version (${projectVersion})`));
+        console.log(chalk.red(`   This would DOWNGRADE your project!\n`));
+        if (!options.allowDowngrade) {
+            console.log(chalk.gray("Solutions:"));
+            console.log(chalk.gray(`  1. Update your CLI: trellis upgrade`));
+            console.log(chalk.gray(`  2. Force downgrade: trellis update --allow-downgrade\n`));
+            return;
+        }
+        console.log(chalk.yellow("⚠️  --allow-downgrade flag set. Proceeding with downgrade...\n"));
+    }
+    // Migration metadata is displayed at the end to prevent scrolling off screen
+    // Load template hashes for modification detection
+    let hashes = loadHashes(cwd);
+    const zcodeConfigured = getConfiguredPlatforms(cwd).has("zcode");
+    const isFirstHashTracking = Object.keys(hashes).length === 0;
+    // Handle unknown version - skip regular migrations but safe-file-delete still runs
+    const isUnknownVersion = projectVersion === "unknown";
+    if (isUnknownVersion) {
+        console.log(chalk.yellow("⚠️  No version file found. Skipping migrations — run trellis init to fix."));
+        console.log(chalk.gray("   Template updates will still be applied."));
+        console.log(chalk.gray("   Safe file cleanup will still run (hash-verified).\n"));
+    }
+    // Detect legacy Codex (has .agents/skills/ tracked by Trellis but no .codex/)
+    // NOTE: this MUST happen before pruneOrphanManifestKeys below, since the
+    // detector reads the raw manifest looking for .agents/skills/ markers that
+    // the prune step would otherwise consider orphans (codex hasn't been added
+    // to configuredPlatforms yet at this point).
+    const codexUpgradeNeeded = needsCodexUpgrade(cwd);
+    if (codexUpgradeNeeded) {
+        console.log(chalk.yellow("  Legacy Codex detected: .agents/skills/ tracked without .codex/ — will create .codex/ directory"));
+    }
+    // Self-heal poisoned manifests: prune entries that no current platform
+    // configurator owns. This silently removes user-owned paths that early
+    // buggy versions of `trellis init` over-hashed (e.g. .codex/sessions/*).
+    // Include codex in known-platforms when codexUpgradeNeeded so legacy Codex
+    // markers under .agents/skills/ survive into the upgrade flow.
+    {
+        const configuredPlatforms = new Set(getConfiguredPlatforms(cwd));
+        if (codexUpgradeNeeded)
+            configuredPlatforms.add("codex");
+        const prune = pruneOrphanManifestKeys(cwd, [...configuredPlatforms], hashes);
+        if (prune.pruned.length > 0) {
+            console.log(chalk.gray(`   Pruned ${prune.pruned.length} orphan manifest entries from .template-hashes.json`));
+            hashes = prune.hashes;
+        }
+    }
+    // For breaking releases with recommendMigrate + --migrate, bypass update.skip
+    // across the board (safe-file-delete, new file writes, template updates).
+    // Why: honoring skip here leaves users forever half-migrated — old deprecated
+    // files persist under skip-protected paths, new commands like `continue.md`
+    // never land, and every future update re-flags the same mess. Rename
+    // migrations already ignore update.skip; this makes the rest consistent
+    // during a breaking upgrade. User customizations are still guarded by the
+    // per-file conflict prompt ("Modified by you") at write time.
+    const breakingBypass = options.migrate === true &&
+        cliVsProject > 0 &&
+        projectVersion !== "unknown" &&
+        (() => {
+            const md = getMigrationMetadata(projectVersion, cliVersion);
+            return md.breaking && md.recommendMigrate;
+        })();
+    // Collect templates (used for both migration classification and change analysis)
+    const templates = await collectTemplateFiles(cwd, codexUpgradeNeeded ? new Set(["codex"]) : undefined, breakingBypass);
+    // Load update.skip paths (used for both safe-file-delete and template collection)
+    const skipPaths = loadUpdateSkipPaths(cwd);
+    // Collect safe-file-delete items from ALL manifests (hash match is the safety net)
+    // This runs regardless of version — unknown version still gets safe cleanup
+    const allMigrations = getAllMigrations();
+    const safeFileDeletes = collectSafeFileDeletes(allMigrations, cwd, skipPaths, new Set(templates.keys()), breakingBypass);
+    const hasSafeDeletes = safeFileDeletes.filter((c) => c.action === "delete").length > 0;
+    // Check for pending regular migrations (skip if unknown version)
+    let pendingMigrations = isUnknownVersion
+        ? []
+        : getMigrationsForVersion(projectVersion, cliVersion);
+    // Also check for "orphaned" migrations - where source still exists but version says we shouldn't migrate
+    // This handles cases where version was updated but migrations weren't applied
+    const orphanedMigrations = allMigrations.filter((item) => {
+        // Only check rename and rename-dir migrations
+        if (item.type !== "rename" && item.type !== "rename-dir")
+            return false;
+        if (!item.from || !item.to)
+            return false;
+        const oldPath = path.join(cwd, item.from);
+        const newPath = path.join(cwd, item.to);
+        // Orphaned if: source exists AND target doesn't exist
+        // AND this migration isn't already in pendingMigrations
+        const sourceExists = fs.existsSync(oldPath);
+        const targetExists = fs.existsSync(newPath);
+        const alreadyPending = pendingMigrations.some((m) => m.from === item.from && m.to === item.to);
+        return sourceExists && !targetExists && !alreadyPending;
+    });
+    // Add orphaned migrations to pending (they need to be applied)
+    if (orphanedMigrations.length > 0) {
+        console.log(chalk.yellow("⚠️  Detected incomplete migrations from previous updates:"));
+        for (const item of orphanedMigrations) {
+            console.log(chalk.yellow(`    ${item.from} → ${item.to}`));
+        }
+        console.log("");
+        pendingMigrations = [...pendingMigrations, ...orphanedMigrations];
+    }
+    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);
+        // Hard-stop: pending rename/delete work from a breaking release requires --migrate.
+        // Why: without --migrate, those entries are skipped and update()'s later path silently
+        // bumps the version stamp, leaving old paths orphaned next to new templates. Force
+        // explicit opt-in so the user can't half-migrate by accident.
+        const pendingMigrationCount = classifiedMigrations.auto.length +
+            classifiedMigrations.confirm.length +
+            classifiedMigrations.conflict.length;
+        if (pendingMigrationCount > 0 &&
+            !options.migrate &&
+            !options.dryRun &&
+            cliVsProject > 0 &&
+            projectVersion !== "unknown") {
+            const gateMetadata = getMigrationMetadata(projectVersion, cliVersion);
+            if (gateMetadata.breaking && gateMetadata.recommendMigrate) {
+                console.log(chalk.bgRed.white.bold(" ✖ MIGRATION REQUIRED ") +
+                    chalk.red(` Breaking changes between ${projectVersion} → ${cliVersion} require --migrate.`));
+                console.log("");
+                console.log(chalk.yellow(`  Run: trellis update --migrate`));
+                console.log("");
+                console.log(chalk.gray("  Without --migrate, renamed/relocated files from breaking releases aren't moved,\n" +
+                    "  leaving your project with stale paths alongside new templates.\n" +
+                    "  Use --dry-run to preview what --migrate will do."));
+                process.exit(1);
+            }
+        }
+        // Soft hint: non-breaking migrations or projects that chose not to set recommendMigrate
+        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("");
+                }
+            }
+        }
+    }
+    // Print safe-file-delete summary (always shown, runs without --migrate)
+    if (safeFileDeletes.length > 0) {
+        printSafeFileDeleteSummary(safeFileDeletes);
+    }
+    // Analyze changes (pass hashes for modification detection)
+    const changes = analyzeChanges(cwd, hashes, templates);
+    const unchangedFileHashRepairs = collectUnchangedFileHashRepairs(changes, hashes);
+    // 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"));
+    }
+    // Ensure project-root .gitattributes carries the journal merge=union rule.
+    // Additive-only (see ensureGitattributes) — runs regardless of whether
+    // other template files changed, so it must sit before the "nothing to do"
+    // early-return below. Never touches disk in --dry-run.
+    if (!options.dryRun) {
+        ensureGitattributes(cwd);
+    }
+    // Check if there's anything to do
+    const isUpgrade = cliVsProject > 0;
+    const isDowngrade = cliVsProject < 0;
+    const isSameVersion = cliVsProject === 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 &&
+        !hasSafeDeletes) {
+        // The "already up to date" exit still has to repair the receipt: this is
+        // exactly the clean tree where every file is `unchanged`, so it is the run
+        // where a wrong entry would otherwise be skipped again.
+        if (!options.dryRun && unchangedFileHashRepairs.size > 0) {
+            updateHashes(cwd, unchangedFileHashRepairs);
+        }
+        if (isSameVersion) {
+            console.log(chalk.green("✓ Already up to date!"));
+        }
+        else {
+            // Version changed but no file changes needed — still update the version stamp
+            updateVersionFile(cwd);
+            if (isUpgrade) {
+                console.log(chalk.green(`✓ No file changes needed for ${projectVersion} → ${cliVersion}`));
+            }
+            else if (isDowngrade) {
+                console.log(chalk.green(`✓ No file changes needed for ${projectVersion} → ${cliVersion} (downgrade)`));
+            }
+        }
+        if (zcodeConfigured)
+            printZcodeSetupHint();
+        return;
+    }
+    // Show what this operation will do
+    if (isUpgrade) {
+        console.log(chalk.green(`This will UPGRADE: ${projectVersion} → ${cliVersion}\n`));
+    }
+    else if (isDowngrade) {
+        console.log(chalk.red(`⚠️  This will DOWNGRADE: ${projectVersion} → ${cliVersion}\n`));
+    }
+    // Show breaking change warning before confirm
+    if (cliVsProject > 0 && projectVersion !== "unknown") {
+        const preConfirmMetadata = getMigrationMetadata(projectVersion, cliVersion);
+        if (preConfirmMetadata.breaking) {
+            console.log(chalk.cyan("═".repeat(60)));
+            console.log(chalk.bgRed.white.bold(" ⚠️  BREAKING CHANGES ") +
+                chalk.red.bold(" Review the changes above carefully!"));
+            if (preConfirmMetadata.changelog.length > 0) {
+                console.log("");
+                console.log(chalk.white(preConfirmMetadata.changelog[0]));
+            }
+            if (preConfirmMetadata.recommendMigrate && !options.migrate) {
+                console.log("");
+                console.log(chalk.bgGreen.black.bold(" 💡 RECOMMENDED ") +
+                    chalk.green.bold(" Run with --migrate to complete the migration"));
+            }
+            // Notice when update.skip is bypassed so user isn't surprised when
+            // skipPaths-protected files get cleaned up during this breaking upgrade.
+            if (breakingBypass && skipPaths.length > 0) {
+                const willBypass = safeFileDeletes.filter((c) => c.action === "delete" &&
+                    skipPaths.some((skip) => c.item.from === skip ||
+                        c.item.from.startsWith(skip.endsWith("/") ? skip : skip + "/")));
+                if (willBypass.length > 0) {
+                    console.log("");
+                    console.log(chalk.bgYellow.black.bold(" ⚠ update.skip BYPASSED ") +
+                        chalk.yellow.bold(` Breaking release — ${willBypass.length.toString()} file(s) under your update.skip paths will be cleaned up.`));
+                    console.log(chalk.gray("  Hash-verified: only files matching known Trellis templates are deleted. Your local customizations (hash mismatch) are still preserved."));
+                }
+            }
+            console.log(chalk.cyan("═".repeat(60)));
+            console.log("");
+        }
+    }
+    // Dry run mode
+    if (options.dryRun) {
+        console.log(chalk.gray("[Dry run] No changes made."));
+        return;
+    }
+    // Batch-resolution flags are explicit consent for non-interactive runs.
+    // Prompting here breaks CI and `node ... update --force --migrate` smoke tests.
+    if (!options.force && !options.skipAll && !options.createNew) {
+        const { proceed } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "proceed",
+                message: "Proceed?",
+                default: true,
+            },
+        ]);
+        if (!proceed) {
+            console.log(chalk.yellow("Update cancelled."));
+            return;
+        }
+    }
+    // Create complete backup of all managed platform/workflow 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,
+        }, templates);
+        printMigrationResult(migrationResult);
+        // Hardcoded: Rename traces-*.md to journal-*.md in workspace directories
+        // Why hardcoded: The migration system only supports fixed path renames, not pattern-based.
+        // traces-*.md files are in .trellis/workspace/{developer}/ with variable developer names
+        // and variable file numbers (traces-1.md, traces-2.md, etc.), so we can't enumerate them
+        // in the migration manifest. This is a one-time migration for the 0.2.0 naming redesign.
+        const workspaceDir = path.join(cwd, PATHS.WORKSPACE);
+        const { renamed: journalRenamed, skipped: journalSkipped } = renameTracesToJournal(workspaceDir);
+        if (journalRenamed > 0) {
+            console.log(chalk.cyan(`Renamed ${journalRenamed} traces file(s) to journal`));
+        }
+        for (const oldPath of journalSkipped) {
+            console.warn(chalk.yellow(`Kept ${path.relative(cwd, oldPath)}: its journal target already exists`));
+        }
+    }
+    // Execute safe-file-delete (after backup, before template writes)
+    let safeDeleted = 0;
+    if (hasSafeDeletes) {
+        safeDeleted = executeSafeFileDeletes(safeFileDeletes, cwd);
+        if (safeDeleted > 0) {
+            console.log(chalk.cyan(`\nCleaned up ${safeDeleted} deprecated command file(s)`));
+        }
+    }
+    // Track results
+    let added = 0;
+    let autoUpdated = 0;
+    let updated = 0;
+    let skipped = 0;
+    let createdNew = 0;
+    // Add new files
+    if (changes.newFiles.length > 0) {
+        console.log(chalk.blue("\nAdding new files..."));
+        for (const file of changes.newFiles) {
+            const dir = path.dirname(file.path);
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(file.path, file.newContent);
+            // Make scripts executable
+            if (file.relativePath.endsWith(".sh") ||
+                file.relativePath.endsWith(".py")) {
+                fs.chmodSync(file.path, "755");
+            }
+            console.log(chalk.green(`  + ${file.relativePath}`));
+            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") ||
+                file.relativePath.endsWith(".py")) {
+                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"));
+        const applyToAll = { action: null };
+        for (const file of changes.changedFiles) {
+            const action = await promptConflictResolution(file, options, applyToAll);
+            if (action === "overwrite") {
+                fs.writeFileSync(file.path, file.newContent);
+                if (file.relativePath.endsWith(".sh") ||
+                    file.relativePath.endsWith(".py")) {
+                    fs.chmodSync(file.path, "755");
+                }
+                console.log(chalk.yellow(`  ✓ Overwritten: ${file.relativePath}`));
+                updated++;
+            }
+            else if (action === "create-new") {
+                const newPath = file.path + ".new";
+                fs.writeFileSync(newPath, file.newContent);
+                console.log(chalk.blue(`  ✓ Created: ${file.relativePath}.new`));
+                createdNew++;
+            }
+            else {
+                console.log(chalk.gray(`  ○ Skipped: ${file.relativePath}`));
+                skipped++;
+            }
+        }
+    }
+    // Append additive config.yaml sections introduced between versions.
+    // Sentinel-gated, so users keep their customizations and re-running update
+    // on already-migrated files is a no-op. Skipped on unknown / downgrade.
+    let configSectionsAppended = 0;
+    if (cliVsProject > 0 && projectVersion !== "unknown") {
+        const sectionEntries = getConfigSectionsAddedBetween(projectVersion, cliVersion);
+        if (sectionEntries.length > 0) {
+            const { appended } = applyConfigSectionsAdded(sectionEntries, cwd, templates);
+            configSectionsAppended = appended;
+        }
+    }
+    // Update version file
+    updateVersionFile(cwd);
+    // Update template hashes for new, auto-updated, and overwritten files
+    const filesToHash = new Map(unchangedFileHashRepairs);
+    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)`);
+    }
+    if (skipped > 0) {
+        console.log(`  Skipped: ${skipped} file(s)`);
+    }
+    if (createdNew > 0) {
+        console.log(`  Created .new copies: ${createdNew} file(s)`);
+    }
+    if (safeDeleted > 0) {
+        console.log(`  Cleaned up: ${safeDeleted} deprecated file(s)`);
+    }
+    if (configSectionsAppended > 0) {
+        console.log(`  Config sections added: ${configSectionsAppended}`);
+    }
+    if (backupDir) {
+        console.log(`  Backup: ${path.relative(cwd, backupDir)}/`);
+    }
+    const actionWord = isDowngrade ? "Downgrade" : "Update";
+    console.log(chalk.green(`\n✅ ${actionWord} complete! (${projectVersion} → ${cliVersion})`));
+    if (createdNew > 0) {
+        console.log(chalk.gray("\nTip: Review .new files and merge changes manually if needed."));
+    }
+    // Create migration task if there are breaking changes with migration guides
+    if (cliVsProject > 0 && projectVersion !== "unknown") {
+        const metadata = getMigrationMetadata(projectVersion, cliVersion);
+        if (metadata.breaking && metadata.migrationGuides.length > 0) {
+            // Create task directory
+            const today = new Date();
+            const monthDay = `${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;
+            const taskSlug = `migrate-to-${cliVersion}`;
+            const taskDirName = `${monthDay}-${taskSlug}`;
+            const tasksDir = path.join(cwd, DIR_NAMES.WORKFLOW, DIR_NAMES.TASKS);
+            const taskDir = path.join(tasksDir, taskDirName);
+            // Check if task already exists
+            if (!fs.existsSync(taskDir)) {
+                fs.mkdirSync(taskDir, { recursive: true });
+                // Get current developer for assignee.
+                // `.developer` is a key=value file (written by init_developer.py):
+                //   name=<developer-name>
+                //   initialized_at=<iso8601>
+                // Reading it raw and .trim()-ing embeds the entire file contents
+                // (including the `name=` prefix and the `initialized_at` line) into
+                // the assignee field, producing bogus assignees like
+                // "name=suyuan\ninitialized_at=2026-04-07T23:41:21.978312" that
+                // later break session-start task rendering.
+                const developerFile = path.join(cwd, DIR_NAMES.WORKFLOW, ".developer");
+                let currentDeveloper = "unknown";
+                if (fs.existsSync(developerFile)) {
+                    const raw = fs.readFileSync(developerFile, "utf-8");
+                    const nameMatch = raw.match(/^\s*name\s*=\s*(.+?)\s*$/m);
+                    if (nameMatch) {
+                        currentDeveloper = nameMatch[1];
+                    }
+                }
+                // Build task.json — canonical 24-field shape via shared factory.
+                const taskTitle = `Migrate to v${cliVersion}`;
+                const todayStr = today.toISOString().split("T")[0];
+                const taskJson = emptyTaskJson({
+                    id: taskSlug,
+                    name: taskSlug,
+                    title: taskTitle,
+                    description: `Breaking change migration from v${projectVersion} to v${cliVersion}`,
+                    status: "planning",
+                    scope: "migration",
+                    priority: "P1",
+                    creator: "trellis-update",
+                    assignee: currentDeveloper,
+                    createdAt: todayStr,
+                });
+                // Write task.json
+                const taskJsonPath = path.join(taskDir, "task.json");
+                fs.writeFileSync(taskJsonPath, JSON.stringify(taskJson, null, 2));
+                // Build PRD content
+                let prdContent = `# Migration Task: Upgrade to v${cliVersion}\n\n`;
+                prdContent += `**Created**: ${todayStr}\n`;
+                prdContent += `**From Version**: ${projectVersion}\n`;
+                prdContent += `**To Version**: ${cliVersion}\n`;
+                prdContent += `**Assignee**: ${currentDeveloper}\n\n`;
+                prdContent += `## Status\n\n- [ ] Review migration guide\n- [ ] Update custom files\n- [ ] Run \`trellis update --migrate\`\n- [ ] Test workflows\n\n`;
+                for (const { version, guide, aiInstructions, } of metadata.migrationGuides) {
+                    prdContent += `---\n\n## v${version} Migration Guide\n\n`;
+                    prdContent += guide;
+                    prdContent += "\n\n";
+                    if (aiInstructions) {
+                        prdContent += `### AI Assistant Instructions\n\n`;
+                        prdContent += `When helping with this migration:\n\n`;
+                        prdContent += aiInstructions;
+                        prdContent += "\n\n";
+                    }
+                }
+                // Write PRD
+                const prdPath = path.join(taskDir, "prd.md");
+                fs.writeFileSync(prdPath, prdContent);
+                console.log("");
+                console.log(chalk.bgCyan.black.bold(" 📋 MIGRATION TASK CREATED "));
+                console.log(chalk.cyan(`A task has been created to help you complete the migration:`));
+                console.log(chalk.white(`   ${DIR_NAMES.WORKFLOW}/${DIR_NAMES.TASKS}/${taskDirName}/`));
+                console.log("");
+                console.log(chalk.gray("Use AI to help: Ask Claude/Cursor to read the task and fix your custom files."));
+            }
+        }
+    }
+    if (zcodeConfigured)
+        printZcodeSetupHint();
+    // Display breaking change warnings at the very end (so they don't scroll off screen)
+    if (cliVsProject > 0 && projectVersion !== "unknown") {
+        const finalMetadata = getMigrationMetadata(projectVersion, cliVersion);
+        if (finalMetadata.breaking || finalMetadata.changelog.length > 0) {
+            console.log("");
+            console.log(chalk.cyan("═".repeat(60)));
+            if (finalMetadata.breaking) {
+                console.log(chalk.bgRed.white.bold(" ⚠️  BREAKING CHANGES ") +
+                    chalk.red.bold(" This update contains breaking changes!"));
+                console.log("");
+            }
+            if (finalMetadata.changelog.length > 0) {
+                console.log(chalk.cyan.bold("📋 What's Changed:"));
+                for (const entry of finalMetadata.changelog) {
+                    console.log(chalk.white(`   ${entry}`));
+                }
+                console.log("");
+            }
+            if (finalMetadata.recommendMigrate && !options.migrate) {
+                console.log(chalk.bgGreen.black.bold(" 💡 RECOMMENDED ") +
+                    chalk.green.bold(" Run with --migrate to complete the migration"));
+                console.log(chalk.gray("   This will remove legacy files and apply all changes."));
+                console.log("");
+            }
+            console.log(chalk.cyan("═".repeat(60)));
+        }
+    }
+}
+//# sourceMappingURL=update.js.map