create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/Harness/scripts/wf-update-check.mjs

@@ -15,7 +15,7 @@
  *   --full-plan and --verbose are aliases.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, lstatSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, lstatSync, unlinkSync } from 'fs';
 import { createHash } from 'crypto';
 import { resolve, dirname, sep } from 'path';
 import { fileURLToPath } from 'url';
@@ -46,6 +46,7 @@ const PRESERVE_PATTERNS = [
   /^Harness\/research\/PRD\.md$/,
   /^Harness\/research\/research-results\.md$/,
   /^Harness\/architecture\.md$/,
+  /^Harness\/project\/architecture\.md$/,
   /^README\.md$/,
   /^\.gitignore$/,
   /^package\.json$/,
@@ -59,6 +60,7 @@ const MERGE_PATTERNS = [
   /^MEMORY\.md$/,
   /^Harness\/MEMORY\.md$/,
   /^Harness\/README\.md$/,
+  /^Harness\/settings\.json$/,
 ];
 
 const OPTIONAL_REGISTRATION_FILES = new Set([
@@ -67,9 +69,25 @@ const OPTIONAL_REGISTRATION_FILES = new Set([
   'Harness/README.md',
 ]);
 
-const BOOTSTRAP_ONLY_FILES = new Set([
-  'Harness/SETUP.md',
-]);
+const HARNESS_OWNED_CANDIDATE_PATTERNS = [
+  /^\.claude\/agents\/[^/]+\.md$/,
+  /^\.opencode\/agents\/[^/]+\.md$/,
+  /^\.claude\/commands\/wf(?:-[^/]+)?\.md$/,
+  /^\.opencode\/commands\/wf(?:-[^/]+)?\.md$/,
+  /^\.claude\/skills\/(?:wf|wf-[^/]+|subagent-orchestrator|tdd)\/SKILL\.md$/,
+  /^\.agents\/skills\/(?:wf|wf-[^/]+|subagent-orchestrator|tdd)\/SKILL\.md$/,
+  /^\.codex\//,
+  /^\.opencode\/plugins\/harness-/,
+  /^Harness\/scripts\//,
+];
+
+const HARNESS_OWNED_CONTENT_MARKERS = [
+  /^harness:\s*(?:wf-agent|wf-framework|create-harness-vibe-coding)\b/im,
+  /\bcreate-harness-vibe-coding\b/i,
+  /\bproject harness\b/i,
+  /\bHarness\/(?:specs|WF|MEMORY|tasks|scripts|subagents|dispatch|context-loading|lifecycle|SETUP)\b/,
+  /\bWF-(?:MAX|AUTO|KERNEL|STATE)\b/,
+];
 
 // Helpers
 
@@ -131,8 +149,11 @@ function optionalSkillFromSource(source) {
   return match ? match[1] : null;
 }
 
+const RETIRED_OPTION_IDS = new Set(['browser-e2e']);
+
 function isInstalledOptionalFile(file, localVersion) {
   const skillId = optionalSkillFromSource(localVersion?.sources?.[file]);
+  if (skillId && RETIRED_OPTION_IDS.has(skillId)) return false;
   return Boolean(skillId && selectedOptionIds(localVersion).has(skillId));
 }
 
@@ -157,18 +178,146 @@ function sha256File(path) {
   return sha256(content);
 }
 
-function classify(file, localHash, storedHash) {
-  // PRESERVE
-  for (const p of PRESERVE_PATTERNS) {
-    if (p.test(file)) return 'PRESERVE';
+// ── Ownership manifest (manifest-first classification) ─────────────────────
+//
+// Harness/ownership.manifest.json is the machine-readable source of truth for
+// file classification. When present it drives PRESERVE/MERGE/frameworkOwned/
+// optionalOwned decisions; the path-regex + content-marker logic below remains
+// as a FALLBACK for old installs that ship no manifest. The updater cannot
+// import from scripts/lib (different package layer), so a small local glob
+// matcher mirrors the one in scripts/lib/ownership-manifest.mjs.
+
+function globToRegex(pattern) {
+  let re = '';
+  let i = 0;
+  while (i < pattern.length) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') {
+      re += '.*';
+      i += 2;
+      if (pattern[i] === '/') i += 1; // swallow a trailing slash after **
+    } else if (c === '*') {
+      re += '[^/]*';
+      i += 1;
+    } else if ('.+?^${}()|[]\\'.includes(c)) {
+      re += '\\' + c;
+      i += 1;
+    } else {
+      re += c;
+      i += 1;
+    }
   }
-  // MERGE: dual-purpose, check if user modified.
-  for (const p of MERGE_PATTERNS) {
-    if (p.test(file)) {
-      if (localHash === storedHash) return 'SAFE'; // unmodified, safe
-      return 'CONFLICT'; // user modified, needs decision
+  return new RegExp('^' + re + '$');
+}
+
+function matchesGlob(dest, pattern) {
+  if (!pattern.includes('*')) return dest === pattern;
+  return globToRegex(pattern).test(dest);
+}
+
+function matchesAnyGlob(dest, patterns) {
+  return (patterns || []).some(p => matchesGlob(dest, p));
+}
+
+function buildOptionalOwnedMap(optionalOwned) {
+  const map = new Map();
+  for (const entry of optionalOwned || []) {
+    if (!entry || typeof entry.option !== 'string') continue;
+    map.set(entry.option, new Set(entry.paths || []));
+  }
+  return map;
+}
+
+/** Load + validate the ownership manifest. Missing/unreadable/invalid -> null (fallback mode). */
+function loadOwnershipManifest(root) {
+  const manifestPath = resolve(root, 'Harness', 'ownership.manifest.json');
+  try {
+    if (!existsSync(manifestPath)) return null;
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.preserve)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function buildManifestCtx(manifest) {
+  if (!manifest) {
+    return { present: false, preserveGlobs: [], mergeSet: new Set(), frameworkOwnedSet: new Set(), optionalOwned: new Map() };
+  }
+  return {
+    present: true,
+    preserveGlobs: manifest.preserve || [],
+    mergeSet: new Set(manifest.merge || []),
+    frameworkOwnedSet: new Set((manifest.frameworkOwned || []).map(e => e && e.path).filter(Boolean)),
+    optionalOwned: buildOptionalOwnedMap(manifest.optionalOwned),
+  };
+}
+
+function isPreserveFile(file, ctx) {
+  if (ctx.present) return matchesAnyGlob(file, ctx.preserveGlobs);
+  return PRESERVE_PATTERNS.some(p => p.test(file));
+}
+
+function isMergeFile(file, ctx) {
+  if (ctx.present) return ctx.mergeSet.has(file);
+  return MERGE_PATTERNS.some(p => p.test(file));
+}
+
+/** Manifest-first declared ownership: frameworkOwned, or optionalOwned whose option is selected. */
+function isDeclaredHarnessOwned(file, ctx, selectedOptions) {
+  if (!ctx.present) return false;
+  if (ctx.frameworkOwnedSet.has(file)) return true;
+  for (const [option, paths] of ctx.optionalOwned) {
+    if (paths.has(file) && selectedOptions.has(option)) return true;
+  }
+  return false;
+}
+
+/** An optional-owned file whose owning option is NOT selected for this install. */
+function isOptionalOwnedUnselected(file, ctx, selectedOptions) {
+  if (!ctx.present) return false;
+  let owned = false;
+  for (const [option, paths] of ctx.optionalOwned) {
+    if (paths.has(file)) {
+      owned = true;
+      if (selectedOptions.has(option)) return false;
     }
   }
+  return owned;
+}
+
+/**
+ * Manifest-first untracked-existing-file ownership. When a remote file is NEW
+ * (not in local checksums) but exists on disk, decide Harness-owned vs
+ * user-owned. The MARKER decides instance ownership: a prior Harness install
+ * leaves a marker, a user-authored file at a Harness-looking path does not.
+ * Manifest declaration (frameworkOwned / installed-optional) and the candidate
+ * regex only build the Harness-interest candidate set; they never by themselves
+ * authorize overwriting an untracked file. A user file at a Harness-interest
+ * path with NO marker stays a conflict (protected) in BOTH manifest and
+ * fallback modes. This matches the installer and AC #5: a user's same-name
+ * agent/command/skill must never be overwritten.
+ */
+function isHarnessOwnedExistingFileManifestFirst(file, diskPath, ctx, selectedOptions) {
+  // A manifest-declared path joins the candidate set, but — like a regex
+  // candidate — still requires a Harness content marker to be adopted. The
+  // marker (not the declaration) decides adopt-vs-conflict for an untracked
+  // existing file, in both manifest and fallback modes.
+  if (isDeclaredHarnessOwned(file, ctx, selectedOptions)) {
+    return fileHasHarnessOwnedMarker(diskPath);
+  }
+  return isHarnessOwnedExistingFile(file, diskPath);
+}
+
+function classify(file, localHash, storedHash, ctx) {
+  // PRESERVE
+  if (isPreserveFile(file, ctx)) return 'PRESERVE';
+  // MERGE: dual-purpose, check if user modified.
+  if (isMergeFile(file, ctx)) {
+    if (localHash === storedHash) return 'SAFE'; // unmodified, safe
+    return 'CONFLICT'; // user modified, needs decision
+  }
   // Everything else is SAFE runtime file: always overwrite.
   // Harness system files (scripts, skills, agents, commands, WF docs) are
   // not user data; the template is authoritative. Only PRESERVE and MERGE
@@ -176,6 +325,25 @@ function classify(file, localHash, storedHash) {
   return 'SAFE';
 }
 
+function isHarnessOwnedCandidate(file) {
+  return HARNESS_OWNED_CANDIDATE_PATTERNS.some(pattern => pattern.test(file));
+}
+
+/** Read on-disk content and test for a Harness ownership marker. */
+function fileHasHarnessOwnedMarker(diskPath) {
+  try {
+    const content = readFileSync(diskPath, 'utf-8');
+    return HARNESS_OWNED_CONTENT_MARKERS.some(pattern => pattern.test(content));
+  } catch {
+    return false;
+  }
+}
+
+function isHarnessOwnedExistingFile(file, diskPath) {
+  if (!isHarnessOwnedCandidate(file)) return false;
+  return fileHasHarnessOwnedMarker(diskPath);
+}
+
 async function fetchRemote(url, timeoutMs = 30000) {
   if (url.startsWith('file://')) {
     return readFileSync(fileURLToPath(url), 'utf-8');
@@ -438,6 +606,12 @@ async function main() {
 
   const localChecksums = localVersion.checksums || {};
 
+  // Ownership manifest: manifest-first classification with regex/marker fallback
+  // for old installs that ship no manifest. manifest=null -> fallback mode.
+  const manifest = loadOwnershipManifest(ROOT);
+  const manifestCtx = buildManifestCtx(manifest);
+  const selectedOptions = selectedOptionIds(localVersion);
+
   // 2. Read remote version metadata from the selected update source.
   let remoteVersion = source?.manifest;
   if (!remoteVersion) {
@@ -493,6 +667,18 @@ async function main() {
 
   const remoteChecksums = remoteVersion.checksums || {};
   const remoteSources = remoteVersion.sources || {};
+  const remoteMoves = Array.isArray(remoteVersion.moves)
+    ? remoteVersion.moves
+        .map(move => ({
+          from: canonicalPath(move?.from || ''),
+          to: canonicalPath(move?.to || ''),
+          deleteOldIfChecksumMatches: move?.deleteOldIfChecksumMatches !== false,
+          preserveOldIfModified: move?.preserveOldIfModified !== false,
+        }))
+        .filter(move => move.from && move.to && remoteChecksums[move.to])
+    : [];
+  const moveByFrom = new Map(remoteMoves.map(move => [move.from, move]));
+  const movedToFiles = new Set();
   localVersion.acceptedConflicts = localVersion.acceptedConflicts || {};
 
   /** Resolve the remote template-relative path for a dest-keyed file. Falls back to the key itself for back-compat. */
@@ -510,6 +696,20 @@ async function main() {
     return source.base + templateRelPath;
   }
 
+  function releaseHighlights(versionObj) {
+    const highlights = versionObj?.releaseNotes?.highlights;
+    return Array.isArray(highlights)
+      ? highlights.map(String).map(s => s.trim()).filter(Boolean)
+      : [];
+  }
+
+  function printReleaseHighlights(versionObj) {
+    const highlights = releaseHighlights(versionObj).slice(0, 6);
+    if (highlights.length === 0) return;
+    console.log('\nRelease highlights:');
+    for (const item of highlights) console.log(`   - ${item}`);
+  }
+
   function withRemoteMeta(entry) {
     if (!entry || !entry.file || !remoteChecksums[entry.file]) return entry;
     const templateHint = remotePath(entry.file);
@@ -544,6 +744,7 @@ async function main() {
       adopted: plan.adopted.map(withRemoteMeta),
       conflict: verbose ? plan.conflict.map(withConflictActions) : plan.conflict.map(withConflictActions).slice(0, 5),
       conflictTruncated: !verbose && plan.conflict.length > 5 ? plan.conflict.length - 5 : undefined,
+      moved: plan.moved.map(withRemoteMeta),
       skipped: plan.skipped.map(withRemoteMeta),
     };
   }
@@ -563,8 +764,12 @@ async function main() {
       safeApplyCommand: 'node Harness/scripts/wf-update-check.mjs --apply-safe',
       strictApplyCommand: 'node Harness/scripts/wf-update-check.mjs --apply',
       finalizeCommand: 'node Harness/scripts/wf-update-check.mjs --finalize',
+      pathMoves: remoteMoves,
       partialUpdate: localVersion.partialUpdate || null,
       acceptedConflicts: localVersion.acceptedConflicts || {},
+      releaseNotes: remoteVersion.releaseNotes || null,
+      releaseHighlights: releaseHighlights(remoteVersion),
+      updateReportRequired: 'After apply/finalize, tell the user the version, safe/new/conflict counts, validation results, and the core releaseHighlights from this update.',
       // aiMergeRequired array is attached only in verbose mode to keep default output token-safe.
       ...(verbose ? { aiMergeRequired: conflicts } : {}),
       aiMergeRequiredCount: totalConflicts,
@@ -615,12 +820,18 @@ async function main() {
     const decision = localVersion.acceptedConflicts?.[file];
     return Boolean(
       decision
-      && decision.targetGenerator === remoteGen
       && decision.localHash === localHash
       && decision.remoteHash === remoteHash
     );
   }
 
+  function acceptedDecisionReason(file) {
+    const decision = localVersion.acceptedConflicts?.[file];
+    if (!decision) return 'accepted conflict decision';
+    if (decision.targetGenerator === remoteGen) return `accepted conflict decision: ${decision.decision}`;
+    return `accepted conflict decision carried forward from ${decision.targetGenerator}: ${decision.decision}`;
+  }
+
   let decisionMetadataDirty = false;
   if (acceptLocal.length || acceptMerged.length || acceptTemplate.length) {
     const appliedAt = new Date().toISOString();
@@ -642,10 +853,11 @@ async function main() {
 
   const allFiles = new Set([...Object.keys(localChecksums), ...Object.keys(remoteChecksums)]);
 
-  const plan = { updated: [], created: [], adopted: [], conflict: [], skipped: [] };
+  const plan = { updated: [], created: [], adopted: [], moved: [], conflict: [], skipped: [] };
 
   for (const file of [...allFiles].sort()) {
     const canonical = canonicalPath(file);
+    if (movedToFiles.has(canonical)) continue;
 
     // Reject paths that escape ROOT before any file access
     const diskPath = safePath(file);
@@ -658,6 +870,47 @@ async function main() {
     const storedHash = localChecksums[file];
     const remoteHash = remoteChecksums[file];
 
+    const move = moveByFrom.get(canonical);
+    if (move && storedHash && !remoteHash) {
+      const toDiskPath = safePath(move.to);
+      if (!toDiskPath) {
+        plan.skipped.push({ file, movedTo: move.to, reason: 'path move target traversal rejected' });
+        continue;
+      }
+      const toLocalHash = sha256File(toDiskPath);
+      const toRemoteHash = remoteChecksums[move.to];
+      if (localHash && localHash !== storedHash) {
+        plan.skipped.push({
+          file,
+          movedTo: move.to,
+          reason: 'legacy moved file modified; preserved for manual review',
+        });
+        continue;
+      }
+      if (toLocalHash && toLocalHash !== toRemoteHash) {
+        plan.skipped.push({
+          file,
+          movedTo: move.to,
+          reason: 'legacy moved file preserved until canonical path conflict is resolved',
+        });
+        continue;
+      }
+      plan.moved.push({
+        file: move.to,
+        from: file,
+        to: move.to,
+        localHash,
+        storedHash,
+        remoteHash: toRemoteHash,
+        write: toLocalHash !== toRemoteHash,
+        reason: toLocalHash === toRemoteHash
+          ? 'legacy framework path cleanup; canonical file already current'
+          : 'safe framework path move',
+      });
+      movedToFiles.add(move.to);
+      continue;
+    }
+
     if (!remoteHash) {
       if (storedHash && isInstalledOptionalFile(file, localVersion)) {
         plan.skipped.push({ file, reason: 'installed optional workflow file' });
@@ -667,8 +920,11 @@ async function main() {
       continue;
     }
 
-    if (BOOTSTRAP_ONLY_FILES.has(canonical) && localHash === null) {
-      plan.skipped.push({ file, reason: 'bootstrap-only file already removed locally' });
+    // Manifest-first: an optional-owned file whose option is NOT selected for
+    // this install is not in this install's plan; skip it rather than
+    // force-applying an optional workflow the user never opted into.
+    if (isOptionalOwnedUnselected(canonical, manifestCtx, selectedOptions)) {
+      plan.skipped.push({ file, reason: 'optional workflow not selected for this install' });
       continue;
     }
 
@@ -680,16 +936,22 @@ async function main() {
           continue;
         }
         if (acceptedDecisionMatches(file, localHash, remoteHash)) {
-          plan.skipped.push({ file, reason: `accepted conflict decision: ${localVersion.acceptedConflicts[file].decision}` });
+          plan.skipped.push({ file, reason: acceptedDecisionReason(file) });
+          continue;
+        }
+        if (isHarnessOwnedExistingFileManifestFirst(canonical, diskPath, manifestCtx, selectedOptions)) {
+          plan.updated.push({ file, localHash, remoteHash, reason: 'existing untracked Harness-owned file' });
           continue;
         }
         plan.conflict.push({ file, localHash, storedHash: 'none', remoteHash, reason: 'new remote file conflicts with existing local file' });
         continue;
       }
-      // New file: still respect PRESERVE classification.
-      const tier = classify(canonical, null, null);
+      // New file: still respect PRESERVE classification for existing user data,
+      // but create missing scaffold starter files. PRESERVE means "do not
+      // overwrite local user data", not "leave required new docs absent".
+      const tier = classify(canonical, null, null, manifestCtx);
       if (tier === 'PRESERVE') {
-        plan.skipped.push({ file, reason: 'PRESERVE: new file would overwrite user data' });
+        plan.created.push({ file, remoteHash, reason: 'PRESERVE: missing scaffold starter; no local user data to overwrite' });
       } else {
         plan.created.push({ file, remoteHash });
       }
@@ -704,7 +966,7 @@ async function main() {
       && localHash !== remoteHash
     ) {
       if (acceptedDecisionMatches(file, localHash, remoteHash)) {
-        plan.skipped.push({ file, reason: `accepted conflict decision: ${localVersion.acceptedConflicts[file].decision}` });
+        plan.skipped.push({ file, reason: acceptedDecisionReason(file) });
         continue;
       }
       plan.conflict.push({
@@ -717,7 +979,7 @@ async function main() {
       continue;
     }
 
-    const tier = classify(canonical, localHash, storedHash);
+    const tier = classify(canonical, localHash, storedHash, manifestCtx);
 
     if (tier === 'PRESERVE') {
       plan.skipped.push({ file, reason: 'PRESERVE: user data' });
@@ -729,7 +991,7 @@ async function main() {
       }
     } else if (tier === 'CONFLICT') {
       if (acceptedDecisionMatches(file, localHash, remoteHash)) {
-        plan.skipped.push({ file, reason: `accepted conflict decision: ${localVersion.acceptedConflicts[file].decision}` });
+        plan.skipped.push({ file, reason: acceptedDecisionReason(file) });
         continue;
       }
       plan.conflict.push({
@@ -737,7 +999,7 @@ async function main() {
         localHash,
         storedHash,
         remoteHash,
-        reason: MERGE_PATTERNS.some(p => p.test(canonical))
+        reason: isMergeFile(canonical, manifestCtx)
           ? 'user modified MERGE file'
           : 'user modified runtime file',
       });
@@ -753,11 +1015,13 @@ async function main() {
       from: localGen,
       to: remoteGen,
       sourceBase,
+      releaseNotes: remoteVersion.releaseNotes || null,
       partialUpdate: localVersion.partialUpdate || null,
       acceptedConflicts: localVersion.acceptedConflicts || {},
       updated: plan.updated.length,
       created: plan.created.length,
       adopted: plan.adopted.length,
+      moved: plan.moved.length,
       conflict: plan.conflict.length,
       skipped: plan.skipped.length,
       // Token-safe by default: attach the full plan only when --verbose / --full-plan is passed.
@@ -768,7 +1032,8 @@ async function main() {
   }
 
   console.log(`\nUpdate: v${localGen} -> v${remoteGen}`);
-  console.log(`   ${plan.updated.length} safe update, ${plan.created.length} new, ${plan.conflict.length} conflict, ${plan.skipped.length} skipped\n`);
+  console.log(`   ${plan.updated.length} safe update, ${plan.created.length} new, ${plan.moved.length} moved, ${plan.conflict.length} conflict, ${plan.skipped.length} skipped\n`);
+  printReleaseHighlights(remoteVersion);
 
   // Show conflicts (these need AI/user decision)
   if (plan.conflict.length > 0) {
@@ -783,10 +1048,11 @@ async function main() {
   }
 
   // Show what will be auto-updated
-  if (plan.updated.length + plan.created.length > 0) {
+  if (plan.updated.length + plan.created.length + plan.moved.length > 0) {
     console.log('AUTO (safe to apply):');
     for (const u of plan.updated) console.log(`   ^ ${u.file}`);
     for (const c of plan.created) console.log(`   + ${c.file}`);
+    for (const m of plan.moved) console.log(`   > ${m.from} -> ${m.to}`);
     console.log('');
   }
 
@@ -809,35 +1075,43 @@ async function main() {
     async function prepareWrite(entry, { mustNotExist = false } = {}) {
       try {
         const dest = safePath(entry.file);
-        if (!dest) { console.error(`   x Traversal rejected: ${entry.file}`); failed++; return; }
+        if (!dest) return { ok: false, message: `   x Traversal rejected: ${entry.file}` };
         // Symlink rejection: do not follow symlinks.
         if (existsSync(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${entry.file}`); failed++; return; } } catch (_) {}
+          try { if (lstatSync(dest).isSymbolicLink()) return { ok: false, message: `   x Symlink rejected: ${entry.file}` }; } catch (_) {}
           if (mustNotExist) {
-            console.error(`   x File created since plan: ${entry.file} - treating as CONFLICT`);
-            failed++; return;
+            return { ok: false, message: `   x File created since plan: ${entry.file} - treating as CONFLICT` };
           }
         }
         const content = await fetchSourceFile(remotePath(entry.file));
         const normalized = content.replace(/\r\n/g, '\n');
         const fetchedHash = sha256(normalized);
         if (fetchedHash !== entry.remoteHash) {
-          console.error(`   x Hash mismatch: ${entry.file}`);
-          failed++; return;
+          return { ok: false, message: `   x Hash mismatch: ${entry.file}` };
         }
-        preparedWrites.push({ file: entry.file, dest, content: normalized, mustNotExist });
+        return { ok: true, prepared: { file: entry.file, dest, content: normalized, mustNotExist } };
       } catch (e) {
-        console.error(`   x Failed: ${entry.file} - ${e.message}`);
-        failed++;
+        return { ok: false, message: `   x Failed: ${entry.file} - ${e.message}` };
       }
     }
 
-    for (const u of plan.updated) {
-      await prepareWrite(u);
-    }
-
-    for (const c of plan.created) {
-      await prepareWrite(c, { mustNotExist: true });
+    const prepareJobs = [
+      ...plan.updated.map(entry => ({ entry, options: {} })),
+      ...plan.created.map(entry => ({ entry, options: { mustNotExist: true } })),
+      ...plan.moved
+        .filter(entry => entry.write !== false)
+        .map(entry => ({ entry, options: { mustNotExist: !existsSync(safePath(entry.file)) } })),
+    ];
+    const prepareResults = await Promise.all(
+      prepareJobs.map(job => prepareWrite(job.entry, job.options)),
+    );
+    for (const result of prepareResults) {
+      if (result.ok) {
+        preparedWrites.push(result.prepared);
+      } else {
+        console.error(result.message);
+        failed++;
+      }
     }
 
     if (failed === 0) {
@@ -849,6 +1123,12 @@ async function main() {
       }
     }
 
+    // All-or-nothing apply invariant: every prepared file above was hash-validated
+    // against its manifest checksum before ANY writeFileSync below. The version
+    // file is advanced only when failed === 0, so a failed apply leaves version
+    // tracking unchanged and is safe to re-run with --apply-safe. A mid-loop
+    // writeFileSync throw (disk failure) is the only partial-disk edge case;
+    // re-running --apply-safe reconciles it.
     let applied = 0;
     if (failed === 0) {
       try {
@@ -857,6 +1137,17 @@ async function main() {
           writeFileSync(prepared.dest, prepared.content, 'utf-8');
           applied++;
         }
+        for (const moved of plan.moved) {
+          const from = safePath(moved.from);
+          if (!from) throw new Error(`Traversal rejected: ${moved.from}`);
+          if (!existsSync(from)) continue;
+          if (lstatSync(from).isSymbolicLink()) throw new Error(`Symlink rejected: ${moved.from}`);
+          const currentHash = sha256File(from);
+          if (currentHash && currentHash !== moved.storedHash) {
+            throw new Error(`Legacy moved file changed before cleanup: ${moved.from}`);
+          }
+          unlinkSync(from);
+        }
       } catch (e) {
         console.error(`   x Failed while writing prepared files - ${e.message}`);
         failed++;
@@ -870,24 +1161,43 @@ async function main() {
       for (const u of plan.updated) localVersion.checksums[u.file] = u.remoteHash;
       for (const c of plan.created) localVersion.checksums[c.file] = c.remoteHash;
       for (const a of plan.adopted) localVersion.checksums[a.file] = a.remoteHash;
+      localVersion.sources = localVersion.sources || {};
+      for (const u of plan.updated) localVersion.sources[u.file] = remoteSources[u.file] || u.file;
+      for (const c of plan.created) localVersion.sources[c.file] = remoteSources[c.file] || c.file;
+      for (const a of plan.adopted) localVersion.sources[a.file] = remoteSources[a.file] || a.file;
+      for (const m of plan.moved) {
+        localVersion.checksums[m.file] = m.remoteHash;
+        localVersion.sources[m.file] = remoteSources[m.file] || m.file;
+        delete localVersion.checksums[m.from];
+        delete localVersion.sources[m.from];
+        delete localVersion.acceptedConflicts[m.from];
+      }
+      if (Array.isArray(remoteVersion.moves)) localVersion.moves = remoteVersion.moves;
+      else delete localVersion.moves;
       if (plan.conflict.length === 0) {
         localVersion.generator = remoteGen;
         localVersion.generated = appliedAt;
+        if (remoteVersion.releaseNotes) localVersion.releaseNotes = remoteVersion.releaseNotes;
+        else delete localVersion.releaseNotes;
         delete localVersion.partialUpdate;
       } else {
         localVersion.partialUpdate = {
           targetGenerator: remoteGen,
           updatedAt: appliedAt,
-          appliedFiles: [...plan.updated, ...plan.created].map(x => x.file),
+          appliedFiles: [...plan.updated, ...plan.created, ...plan.moved].map(x => x.file),
           adoptedFiles: plan.adopted.map(x => x.file),
+          movedFiles: plan.moved.map(x => ({ from: x.from, to: x.to })),
           conflicts: plan.conflict.map(x => x.file),
+          releaseNotes: remoteVersion.releaseNotes || null,
         };
       }
       writeFileSync(VERSION_FILE, JSON.stringify(localVersion, null, 2) + '\n', 'utf-8');
       if (plan.conflict.length === 0) {
         console.log(`Applied ${applied} files. Version updated to ${remoteVersion.generator}.`);
+        printReleaseHighlights(remoteVersion);
       } else {
         console.log(`Applied ${applied} SAFE/NEW files. Version remains ${localGen}; ${plan.conflict.length} conflicts still need merge.`);
+        printReleaseHighlights(remoteVersion);
       }
     } else {
       console.log(`${failed} failures. NO files were version-tracked. Fix and re-run.`);
@@ -896,8 +1206,8 @@ async function main() {
   }
 
   if (finalize) {
-    if (plan.updated.length > 0 || plan.created.length > 0 || plan.adopted.length > 0) {
-      console.log(`Cannot finalize: ${plan.updated.length} safe updates, ${plan.created.length} new files, and ${plan.adopted.length} adopted metadata entries still need --apply-safe.`);
+    if (plan.updated.length > 0 || plan.created.length > 0 || plan.adopted.length > 0 || plan.moved.length > 0) {
+      console.log(`Cannot finalize: ${plan.updated.length} safe updates, ${plan.created.length} new files, ${plan.moved.length} path moves, and ${plan.adopted.length} adopted metadata entries still need --apply-safe.`);
       if (decisionMetadataDirty) {
         writeFileSync(VERSION_FILE, JSON.stringify(localVersion, null, 2) + '\n', 'utf-8');
       }
@@ -915,9 +1225,12 @@ async function main() {
     const finalizedAt = new Date().toISOString();
     localVersion.generator = remoteGen;
     localVersion.generated = finalizedAt;
+    if (remoteVersion.releaseNotes) localVersion.releaseNotes = remoteVersion.releaseNotes;
+    else delete localVersion.releaseNotes;
     delete localVersion.partialUpdate;
     writeFileSync(VERSION_FILE, JSON.stringify(localVersion, null, 2) + '\n', 'utf-8');
     console.log(`Finalized Harness update to ${remoteGen}.`);
+    printReleaseHighlights(remoteVersion);
   } else if (decisionMetadataDirty) {
     writeFileSync(VERSION_FILE, JSON.stringify(localVersion, null, 2) + '\n', 'utf-8');
     console.log('Recorded conflict decision metadata.');