@pennixrv/trellis 0.7.0-beta.5 → 0.7.0-beta.50

package/dist/commands/update.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import chalk from "chalk";
 import inquirer from "inquirer";
 import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
+import { BACKUP_COMPLETE_MARKER, BACKUP_PRUNE_LOCK } from "./backup.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";
@@ -20,14 +21,16 @@ import { COPILOT_INSTRUCTIONS_BLOCK_END, COPILOT_INSTRUCTIONS_BLOCK_START, COPIL
 import { ALL_MANAGED_DIRS, getConfiguredPlatforms, collectPlatformTemplates, } from "../configurators/index.js";
 import { replacePythonCommandLiterals } from "../configurators/shared.js";
 import { CLAUDE_STATUSLINE_PATH, isClaudeStatuslineManaged, } from "../configurators/claude.js";
-import { preserveCodexAgentModelKeys } from "../configurators/codex.js";
+import { preserveCodexAgentModelKeys, preserveCodexProjectConfig, } from "../configurators/codex.js";
 import { printZcodeSetupHint } from "../configurators/zcode.js";
 import { ensureGitattributes } from "../configurators/workflow.js";
 import { getStatuslineHook } from "../templates/claude/index.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, getManagedMarkdownBlock, mergeManagedMarkdownBlock, TRELLIS_BLOCK_END, TRELLIS_BLOCK_START, } from "../utils/managed-paths.js";
+import { cleanupEmptyDirs, getManagedMarkdownBlock, mergeManagedMarkdownBlock, reportAgentsOverride, TRELLIS_BLOCK_END, TRELLIS_BLOCK_START, } from "../utils/managed-paths.js";
+import { loadWorkflowProvenance, writeWorkflowProvenance, workflowProvenanceMismatches, } from "../utils/workflow-provenance.js";
+import { NATIVE_WORKFLOW_ID, resolveWorkflowTemplate, } from "../utils/workflow-resolver.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([
@@ -37,73 +40,6 @@ const LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES = new Set([
     // false "modified by you" conflict.
     "c1f511b1cfc1902f2147da159f09cc51f380b0c9e341cdb3ac5dea5233f3e307",
 ]);
-const CODEX_WORKFLOW_STATE_HOOK_PATH = ".codex/hooks/inject-workflow-state.py";
-const LEGACY_PENNIX_CODEX_DISPATCH_SIGNATURES = [
-    "def _resolve_codex_dispatch_mode(config: dict, repo_root: Path | None = None) -> str:",
-    "from common.config import get_workflow_dispatch_mode",
-    "return get_workflow_dispatch_mode(root, config=config)",
-];
-const LEGACY_PENNIX_ACTIVE_TASK_GUARD = "    active = _resolve_active_task(root, input_data)\n" +
-    "    if not active.task_path:\n" +
-    "        return None";
-const PENNIX_AMBIGUITY_PROJECTION = "    active = _resolve_active_task(root, input_data)\n" +
-    '    if active.source_type == "unbound_ambiguous":\n' +
-    '        candidates = ", ".join(active.candidate_paths)\n' +
-    '        return candidates, "unbound_ambiguous", active.source\n' +
-    "    if not active.task_path:\n" +
-    "        return None";
-const LEGACY_PENNIX_BREADCRUMB_HEADER = '    header = f"Status: {status}" if task_id is None else f"Task: {task_id} ({status})"';
-const PENNIX_AMBIGUITY_BREADCRUMB_HEADER = '    if status == "unbound_ambiguous":\n' +
-    '        header = f"Status: {status}\\nCandidates: {task_id}"\n' +
-    "    else:\n" +
-    '        header = f"Status: {status}" if task_id is None else f"Task: {task_id} ({status})"';
-/**
- * Preserve the historical Pennix Codex hook while adding the one projection
- * it predates. This is intentionally stricter than hash tracking: the Hook
- * carried a Pennix-specific dispatch resolver, so pristine installations were
- * correctly classified as locally modified and never received issue #180.
- */
-function migrateLegacyPennixCodexWorkflowHook(relativePath, existingContent) {
-    if (relativePath !== CODEX_WORKFLOW_STATE_HOOK_PATH ||
-        !LEGACY_PENNIX_CODEX_DISPATCH_SIGNATURES.every((signature) => existingContent.includes(signature))) {
-        return null;
-    }
-    const hasProjection = existingContent.includes(PENNIX_AMBIGUITY_PROJECTION);
-    const hasHeader = existingContent.includes(PENNIX_AMBIGUITY_BREADCRUMB_HEADER);
-    if (hasProjection && hasHeader) {
-        return { content: existingContent, needsUpdate: false };
-    }
-    if ((!hasProjection &&
-        !existingContent.includes(LEGACY_PENNIX_ACTIVE_TASK_GUARD)) ||
-        (!hasHeader && !existingContent.includes(LEGACY_PENNIX_BREADCRUMB_HEADER))) {
-        return null;
-    }
-    return {
-        content: existingContent
-            .replace(LEGACY_PENNIX_ACTIVE_TASK_GUARD, PENNIX_AMBIGUITY_PROJECTION)
-            .replace(LEGACY_PENNIX_BREADCRUMB_HEADER, PENNIX_AMBIGUITY_BREADCRUMB_HEADER),
-        needsUpdate: !hasProjection || !hasHeader,
-    };
-}
-/** Keep recognized Pennix Hook customizations in the desired template map. */
-function preserveLegacyPennixCodexWorkflowHook(cwd, templates) {
-    if (!templates.has(CODEX_WORKFLOW_STATE_HOOK_PATH)) {
-        return;
-    }
-    const hookPath = path.join(cwd, CODEX_WORKFLOW_STATE_HOOK_PATH);
-    if (!fs.existsSync(hookPath)) {
-        return;
-    }
-    try {
-        const migration = migrateLegacyPennixCodexWorkflowHook(CODEX_WORKFLOW_STATE_HOOK_PATH, fs.readFileSync(hookPath, "utf-8"));
-        if (migration) {
-            templates.set(CODEX_WORKFLOW_STATE_HOOK_PATH, migration.content);
-        }
-    }
-    catch {
-        // The normal conflict path reports unreadable or concurrently changed files.
-    }
-}
 // 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 = [
@@ -127,6 +63,31 @@ function buildManagedBlockTemplate(cwd, relativePath, templateContent, startMark
 function buildAgentsMdTemplate(cwd) {
     return buildManagedBlockTemplate(cwd, FILE_NAMES.AGENTS, agentsMdContent, TRELLIS_BLOCK_START, TRELLIS_BLOCK_END);
 }
+function countOccurrences(content, needle) {
+    return content.split(needle).length - 1;
+}
+/**
+ * A generated Markdown file can contain a user-owned document around one
+ * Trellis-managed block. If only that block changed, the whole file is still
+ * an update owned by Trellis and must not enter the user-conflict path.
+ */
+function isManagedMarkdownBlockOnlyChange(relativePath, existingContent, newContent) {
+    if (relativePath !== FILE_NAMES.AGENTS)
+        return false;
+    if (countOccurrences(existingContent, TRELLIS_BLOCK_START) !== 1 ||
+        countOccurrences(existingContent, TRELLIS_BLOCK_END) !== 1 ||
+        countOccurrences(newContent, TRELLIS_BLOCK_START) !== 1 ||
+        countOccurrences(newContent, TRELLIS_BLOCK_END) !== 1) {
+        return false;
+    }
+    const existingBlock = getTrellisManagedBlock(existingContent);
+    const newBlock = getTrellisManagedBlock(newContent);
+    return (existingBlock !== null &&
+        newBlock !== null &&
+        existingBlock !== newBlock &&
+        existingContent.replace(existingBlock, "") ===
+            newContent.replace(newBlock, ""));
+}
 function buildCopilotInstructionsTemplate(cwd) {
     return buildManagedBlockTemplate(cwd, COPILOT_INSTRUCTIONS_PATH, getCopilotInstructions(), COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_BLOCK_END);
 }
@@ -134,6 +95,9 @@ function isKnownUntrackedTemplate(relativePath, existingContent) {
     if (relativePath !== FILE_NAMES.AGENTS) {
         return false;
     }
+    if (countOccurrences(existingContent, TRELLIS_BLOCK_START) !== 1 ||
+        countOccurrences(existingContent, TRELLIS_BLOCK_END) !== 1)
+        return false;
     const managedBlock = getTrellisManagedBlock(existingContent);
     if (!managedBlock) {
         return false;
@@ -513,6 +477,58 @@ function preserveExistingRegistryConfig(cwd, template) {
         `    source: ${registry.source}\n` +
         (registry.template ? `    template: ${registry.template}\n` : ""));
 }
+/**
+ * Preserve top-level YAML sections not declared by the Trellis template.
+ * Project extensions are identified by structure, not by Pennix-specific key
+ * names; `registry` remains handled by its existing normalized path.
+ */
+function preserveExistingConfigExtensions(cwd, template) {
+    const configPath = path.join(cwd, DIR_NAMES.WORKFLOW, "config.yaml");
+    if (!fs.existsSync(configPath)) {
+        return template;
+    }
+    const existing = fs.readFileSync(configPath, "utf-8");
+    const sectionPattern = /^([A-Za-z_][A-Za-z0-9_-]*):(?:\s|$)/;
+    const sections = (content) => {
+        const lines = content.split(/\r?\n/);
+        const starts = [];
+        for (let index = 0; index < lines.length; index += 1) {
+            const match = lines[index]?.match(sectionPattern);
+            if (match?.[1])
+                starts.push({ key: match[1], index });
+        }
+        return new Map(starts.map(({ key, index }, position) => [
+            key,
+            {
+                content: lines
+                    .slice(index, starts[position + 1]?.index ?? lines.length)
+                    .join("\n"),
+                index,
+            },
+        ]));
+    };
+    const templateSections = sections(template);
+    const templateKeys = new Set(templateSections.keys());
+    const existingSections = sections(existing);
+    const templateLines = new Set(template.split(/\r?\n/));
+    const extensions = [...existingSections].filter(([key]) => key !== "registry" && !templateKeys.has(key));
+    const withRegistry = preserveExistingRegistryConfig(cwd, template);
+    if (extensions.length === 0)
+        return withRegistry;
+    // Keep project comments that introduce an extension, but do not duplicate
+    // the template's trailing documentation when the extension was appended
+    // directly after a generated section. The line-based parser intentionally
+    // stays limited to the generated top-level YAML shape.
+    const extensionContent = extensions.map(([, section]) => {
+        const preceding = existing
+            .split(/\r?\n/)
+            .slice(Math.max(0, section.index - 32), section.index);
+        const projectComments = preceding.filter((line) => line.trimStart().startsWith("#") && !templateLines.has(line));
+        const leading = projectComments.length > 0 ? `${projectComments.join("\n")}\n` : "";
+        return `${leading}${section.content.trimEnd()}`;
+    });
+    return `${withRegistry.trimEnd()}\n${extensionContent.join("\n\n")}\n`;
+}
 async function collectRegistrySpecTemplates(cwd) {
     const config = loadSpecRegistryConfig(cwd);
     if (!config)
@@ -589,16 +605,15 @@ bypassUpdateSkip = false) {
         files.set(`${PATHS.AGENTS}/${agentFile}`, content);
     }
     // Configuration
-    files.set(`${DIR_NAMES.WORKFLOW}/config.yaml`, preserveExistingRegistryConfig(cwd, configYamlTemplate));
+    files.set(`${DIR_NAMES.WORKFLOW}/config.yaml`, preserveExistingConfigExtensions(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);
+    // workflow.md is runtime-parsed by get_context.py and shared hooks. Keep it
+    // on the normal whole-file update path, but resolve the project's selected
+    // workflow instead of silently substituting the bundled native workflow.
+    const selectedWorkflow = await resolveWorkflowUpdateTemplate(cwd, hashes);
+    if (selectedWorkflow !== null) {
+        files.set(`${DIR_NAMES.WORKFLOW}/workflow.md`, selectedWorkflow);
+    }
     // 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));
@@ -621,7 +636,7 @@ bypassUpdateSkip = false) {
     // as a modified-file conflict by the hash comparison below.
     if (platforms.has("codex")) {
         preserveCodexAgentModelKeys(cwd, files);
-        preserveLegacyPennixCodexWorkflowHook(cwd, files);
+        preserveCodexProjectConfig(cwd, files);
     }
     preserveExistingClaudeStatusLine(cwd, files);
     if (platforms.has("claude-code") && isClaudeStatuslineManaged(cwd, hashes)) {
@@ -648,6 +663,55 @@ bypassUpdateSkip = false) {
     }
     return files;
 }
+/**
+ * Resolve the workflow selected by this project for generic updates.
+ *
+ * Provenance is the durable source of truth for marketplace workflows. Older
+ * projects without provenance retain their historical behavior: hash-tracked
+ * workflow.md uses the bundled template, while an untracked custom workflow
+ * remains outside the generic update set.
+ */
+async function resolveWorkflowUpdateTemplate(cwd, hashes) {
+    const provenance = loadWorkflowProvenance(cwd);
+    if (!provenance) {
+        return hashes[PATHS.WORKFLOW_GUIDE_FILE] ? workflowMdTemplate : null;
+    }
+    const template = await resolveWorkflowTemplate(provenance.workflow_id, {
+        source: provenance.source_kind === "marketplace"
+            ? provenance.registry
+            : undefined,
+    });
+    const nativeVersionTransition = template.id === NATIVE_WORKFLOW_ID &&
+        template.source === "bundled" &&
+        provenance.ref !== template.ref &&
+        compareVersions(provenance.ref, template.ref) !== null;
+    const mismatches = workflowProvenanceMismatches(provenance, template).filter((mismatch) => !(nativeVersionTransition &&
+        (mismatch === "ref" ||
+            (mismatch === "template integrity" &&
+                hashes[PATHS.WORKFLOW_GUIDE_FILE] === provenance.content_sha256))));
+    if (mismatches.length > 0) {
+        throw new Error(`Workflow provenance verification failed: ${mismatches.join(", ")}.`);
+    }
+    return template.id === NATIVE_WORKFLOW_ID
+        ? workflowMdTemplate
+        : template.content;
+}
+function refreshNativeWorkflowProvenance(cwd) {
+    const record = loadWorkflowProvenance(cwd);
+    if (record?.source_kind !== "bundled" ||
+        record.workflow_id !== NATIVE_WORKFLOW_ID)
+        return;
+    const workflowPath = path.join(cwd, PATHS.WORKFLOW_GUIDE_FILE);
+    if (fs.existsSync(workflowPath) &&
+        fs.readFileSync(workflowPath, "utf-8") ===
+            replacePythonCommandLiterals(workflowMdTemplate)) {
+        writeWorkflowProvenance(cwd, {
+            ...record,
+            ref: VERSION,
+            content_sha256: computeHash(workflowMdTemplate),
+        });
+    }
+}
 /**
  * Analyze changes between current files and templates
  *
@@ -687,11 +751,15 @@ function analyzeChanges(cwd, hashes, templates) {
         }
         else {
             const existingContent = fs.readFileSync(fullPath, "utf-8");
-            const legacyPennixHook = migrateLegacyPennixCodexWorkflowHook(relativePath, existingContent);
-            if (legacyPennixHook?.needsUpdate &&
-                newContent === legacyPennixHook.content) {
+            const markers = relativePath === FILE_NAMES.AGENTS
+                ? [TRELLIS_BLOCK_START, TRELLIS_BLOCK_END]
+                : relativePath === COPILOT_INSTRUCTIONS_PATH
+                    ? [COPILOT_INSTRUCTIONS_BLOCK_START, COPILOT_INSTRUCTIONS_BLOCK_END]
+                    : null;
+            if (markers &&
+                mergeManagedMarkdownBlock(existingContent, newContent, markers[0], markers[1]) === null) {
                 change.status = "changed";
-                result.autoUpdateFiles.push(change);
+                result.changedFiles.push(change);
                 continue;
             }
             if (existingContent === newContent) {
@@ -713,6 +781,12 @@ function analyzeChanges(cwd, hashes, templates) {
                     change.status = "changed";
                     result.autoUpdateFiles.push(change);
                 }
+                else if (isManagedMarkdownBlockOnlyChange(relativePath, existingContent, newContent)) {
+                    // The project-owned prose around AGENTS.md is unchanged; only the
+                    // explicitly managed Trellis block moved to a new template version.
+                    change.status = "changed";
+                    result.autoUpdateFiles.push(change);
+                }
                 else {
                     // Hash differs (or no stored hash) - user modified the file
                     // Needs confirmation
@@ -955,6 +1029,7 @@ export function shouldExcludeFromBackup(relativePath) {
  */
 function createFullBackup(cwd) {
     const backupDir = createBackupDirPath(cwd);
+    const stagingDir = `${backupDir}.incomplete`;
     let hasFiles = false;
     for (const dir of BACKUP_DIRS) {
         const dirPath = path.join(cwd, dir);
@@ -968,10 +1043,10 @@ function createFullBackup(cwd) {
                 continue;
             // Create backup
             if (!hasFiles) {
-                fs.mkdirSync(backupDir, { recursive: true });
+                fs.mkdirSync(stagingDir, { recursive: true });
                 hasFiles = true;
             }
-            backupFile(cwd, backupDir, relativePath);
+            backupFile(cwd, stagingDir, relativePath);
         }
     }
     for (const relativePath of BACKUP_FILES) {
@@ -981,10 +1056,14 @@ function createFullBackup(cwd) {
         if (shouldExcludeFromBackup(relativePath))
             continue;
         if (!hasFiles) {
-            fs.mkdirSync(backupDir, { recursive: true });
+            fs.mkdirSync(stagingDir, { recursive: true });
             hasFiles = true;
         }
-        backupFile(cwd, backupDir, relativePath);
+        backupFile(cwd, stagingDir, relativePath);
+    }
+    if (hasFiles) {
+        fs.writeFileSync(path.join(stagingDir, BACKUP_COMPLETE_MARKER), VERSION, "utf8");
+        fs.renameSync(stagingDir, backupDir);
     }
     return hasFiles ? backupDir : null;
 }
@@ -1224,7 +1303,9 @@ export function classifyMigrations(migrations, cwd, hashes, templates) {
             const newExists = fs.existsSync(newPath);
             if (newExists) {
                 // Target exists - check if it only contains unmodified template files
-                if (isDirectorySafeToReplace(cwd, item.to, hashes, templates)) {
+                if (isDirectorySafeToReplace(cwd, item.to, hashes, templates) &&
+                    (!dirMatchesCurrentTemplates(cwd, item.to, templates) ||
+                        isDirectorySafeToReplace(cwd, item.from, hashes, templates))) {
                     // Safe to delete target and rename source
                     result.auto.push(item);
                 }
@@ -1451,6 +1532,11 @@ export async function executeMigrations(classified, cwd, options, templates) {
             // flavored bytes, so just drop the now-redundant source instead (#447).
             if (fs.existsSync(newPath) &&
                 dirMatchesCurrentTemplates(cwd, item.to, templates)) {
+                if (!isDirectorySafeToReplace(cwd, item.from, loadHashes(cwd), templates)) {
+                    result.skipped++;
+                    console.log(chalk.yellow("  ○ Preserved modified migration source: " + item.from));
+                    continue;
+                }
                 removeDirectoryRecursive(oldPath);
                 const hashes = loadHashes(cwd);
                 const updatedHashes = {};
@@ -1633,6 +1719,7 @@ export async function update(options) {
     }
     console.log(chalk.cyan("\nTrellis Update"));
     console.log(chalk.cyan("══════════════\n"));
+    reportAgentsOverride(cwd);
     // Set up proxy before any network calls (npm version check)
     setupProxy();
     // Get versions
@@ -1865,6 +1952,8 @@ export async function update(options) {
         }
         if (zcodeConfigured)
             printZcodeSetupHint();
+        if (!options.dryRun)
+            refreshNativeWorkflowProvenance(cwd);
         return;
     }
     // Show what this operation will do
@@ -1928,277 +2017,301 @@ export async function update(options) {
             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)`));
+    // Keep the rollback snapshot protected until all update writes finish.
+    const backupLockPath = path.join(cwd, DIR_NAMES.WORKFLOW, BACKUP_PRUNE_LOCK);
+    const backupLock = fs.openSync(backupLockPath, "wx");
+    try {
+        // 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`));
+            }
         }
-    }
-    // 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");
+        // 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)`));
             }
-            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");
+        // 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++;
             }
-            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") {
+        // 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.yellow(`  ✓ Overwritten: ${file.relativePath}`));
-                updated++;
+                console.log(chalk.cyan(`  ↑ ${file.relativePath}`));
+                autoUpdated++;
             }
-            else if (action === "create-new") {
-                const newPath = file.path + ".new";
-                fs.writeFileSync(newPath, file.newContent);
-                console.log(chalk.blue(`  ✓ Created: ${file.relativePath}.new`));
-                createdNew++;
+        }
+        // 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") {
+                    const markers = file.relativePath === FILE_NAMES.AGENTS
+                        ? [TRELLIS_BLOCK_START, TRELLIS_BLOCK_END]
+                        : file.relativePath === COPILOT_INSTRUCTIONS_PATH
+                            ? [
+                                COPILOT_INSTRUCTIONS_BLOCK_START,
+                                COPILOT_INSTRUCTIONS_BLOCK_END,
+                            ]
+                            : null;
+                    if (markers &&
+                        mergeManagedMarkdownBlock(fs.readFileSync(file.path, "utf-8"), file.newContent, markers[0], markers[1]) === null) {
+                        throw new Error("Refusing ambiguous managed Markdown markers in " +
+                            file.relativePath +
+                            "; use --create-new or repair the markers.");
+                    }
+                    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++;
+                }
             }
-            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;
             }
         }
-    }
-    // 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);
+        // Update version file
+        updateVersionFile(cwd);
+        refreshNativeWorkflowProvenance(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];
+        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;
+                    // 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."));
                 }
-                // 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!"));
+        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("");
-            }
-            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(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("");
                 }
-                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("");
+                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)));
             }
-            console.log(chalk.cyan("═".repeat(60)));
         }
     }
+    finally {
+        fs.closeSync(backupLock);
+        fs.rmSync(backupLockPath, { force: true });
+    }
 }
 //# sourceMappingURL=update.js.map