create-harness-vibe-coding 0.8.12 → 0.8.16

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

@@ -15,19 +15,26 @@
  *   --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';
+import { gunzipSync } from 'zlib';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.WF_ROOT ? resolve(process.env.WF_ROOT) : resolve(__dirname, '..', '..');
 const VERSION_FILE = resolve(ROOT, 'Harness', '.harness-version');
+const NPM_PACKAGE = 'create-harness-vibe-coding';
+const NPM_REGISTRY = (process.env.NPM_CONFIG_REGISTRY || 'https://registry.npmjs.org').replace(/\/+$/, '');
 const GITHUB_REPO = 'LiWeny16/create-harness-vibe-coding';
+const LEGACY_GITHUB_REPO = 'zingspark/create-harness-vibe-coding';
 const GITHUB_LATEST_STABLE = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
 const RAW_GITHUB = `https://raw.githubusercontent.com/${GITHUB_REPO}`;
+const LEGACY_RAW_GITHUB = `https://raw.githubusercontent.com/${LEGACY_GITHUB_REPO}`;
 const TEMPLATE_SUBPATH = 'templates/common/';
 const DEFAULT_SOURCE_BASE = `${RAW_GITHUB}/main/${TEMPLATE_SUBPATH}`;
+const LEGACY_SOURCE_BASE = `${LEGACY_RAW_GITHUB}/main/${TEMPLATE_SUBPATH}`;
+const npmPackageCache = new Map();
 
 // Tier classification
 
@@ -39,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$/,
@@ -52,6 +60,7 @@ const MERGE_PATTERNS = [
   /^MEMORY\.md$/,
   /^Harness\/MEMORY\.md$/,
   /^Harness\/README\.md$/,
+  /^Harness\/settings\.json$/,
 ];
 
 const OPTIONAL_REGISTRATION_FILES = new Set([
@@ -60,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
 
@@ -150,18 +175,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
@@ -169,6 +322,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');
@@ -185,6 +357,47 @@ async function fetchRemote(url, timeoutMs = 30000) {
   }
 }
 
+async function fetchBytes(url, timeoutMs = 30000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { 'User-Agent': 'harness-wf-update-check' } });
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+    return Buffer.from(await res.arrayBuffer());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function tarString(header, start, length) {
+  const slice = header.subarray(start, start + length);
+  const zero = slice.indexOf(0);
+  return Buffer.from(zero === -1 ? slice : slice.subarray(0, zero)).toString('utf8').trim();
+}
+
+function parseTarFiles(buffer) {
+  const files = new Map();
+  for (let offset = 0; offset + 512 <= buffer.length;) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every(byte => byte === 0)) break;
+
+    const name = tarString(header, 0, 100);
+    const prefix = tarString(header, 345, 155);
+    const sizeText = tarString(header, 124, 12);
+    const size = Number.parseInt(sizeText || '0', 8) || 0;
+    const type = String.fromCharCode(header[156] || 0);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    const dataStart = offset + 512;
+
+    if ((type === '\0' || type === '0' || type === '') && fullName) {
+      files.set(fullName, buffer.subarray(dataStart, dataStart + size));
+    }
+
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+
 // Main
 
 function isPrerelease(v) {
@@ -192,7 +405,74 @@ function isPrerelease(v) {
   return /-[0-9A-Za-z.-]+/.test(v.replace(/^[^0-9]*/, ''));
 }
 
-async function resolveStableSourceBase() {
+function parseSemver(v) {
+  if (!v || typeof v !== 'string') return [0, 0, 0];
+  return v.replace(/^[^0-9]*/, '').split('.').slice(0, 3).map(n => Number(n) || 0);
+}
+
+function cmpSemver(a, b) {
+  const va = parseSemver(a), vb = parseSemver(b);
+  for (let i = 0; i < 3; i++) {
+    if ((va[i] || 0) > (vb[i] || 0)) return 1;
+    if ((va[i] || 0) < (vb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+async function loadNpmPackage(version = 'latest') {
+  const cacheKey = `${NPM_REGISTRY}:${version}`;
+  if (npmPackageCache.has(cacheKey)) return npmPackageCache.get(cacheKey);
+
+  const metaUrl = `${NPM_REGISTRY}/${NPM_PACKAGE}/${version}`;
+  const meta = JSON.parse(await fetchRemote(metaUrl, 15000));
+  const packageVersion = meta.version;
+  const tarball = meta?.dist?.tarball;
+  if (!packageVersion || !tarball) throw new Error(`npm metadata missing dist.tarball for ${NPM_PACKAGE}@${version}`);
+
+  const archive = gunzipSync(await fetchBytes(tarball, 30000));
+  const files = parseTarFiles(archive);
+  const loaded = { version: packageVersion, tarball, files };
+  npmPackageCache.set(cacheKey, loaded);
+  npmPackageCache.set(`${NPM_REGISTRY}:${packageVersion}`, loaded);
+  return loaded;
+}
+
+function readNpmFile(pkg, templateRelPath) {
+  const key = `package/${TEMPLATE_SUBPATH}${templateRelPath}`;
+  const content = pkg.files.get(key);
+  if (!content) throw new Error(`npm package missing ${key}`);
+  return Buffer.from(content).toString('utf8');
+}
+
+async function createNpmSource(version = 'latest') {
+  const pkg = await loadNpmPackage(version);
+  const raw = readNpmFile(pkg, '.harness-version');
+  if (isTemplate(raw)) throw new Error('npm .harness-version has not been generated yet');
+  const manifest = JSON.parse(raw);
+  return {
+    kind: 'npm',
+    stable: true,
+    label: `npm:${NPM_PACKAGE}@${pkg.version}/${TEMPLATE_SUBPATH}`,
+    version: pkg.version,
+    manifest,
+    package: pkg,
+  };
+}
+
+async function createUrlSource(sourceBase, { stable = false } = {}) {
+  const base = normalizeSourceBase(sourceBase);
+  const raw = await fetchRemote(base + '.harness-version');
+  if (isTemplate(raw)) throw new Error('remote .harness-version has not been generated yet');
+  return {
+    kind: 'url',
+    stable,
+    label: base,
+    base,
+    manifest: JSON.parse(raw),
+  };
+}
+
+async function resolveGithubReleaseSource() {
   try {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 15000);
@@ -209,26 +489,45 @@ async function resolveStableSourceBase() {
     const data = JSON.parse(await res.text());
     const tag = data && data.tag_name;
     if (!tag || data.prerelease) return null;
-    const source = `${RAW_GITHUB}/${tag}/${TEMPLATE_SUBPATH}`;
-    const versionController = new AbortController();
-    const versionTimer = setTimeout(() => versionController.abort(), 15000);
-    try {
-      const versionRes = await fetch(source + '.harness-version', {
-        signal: versionController.signal,
-        headers: { 'User-Agent': 'harness-wf-update-check' },
-      });
-      if (!versionRes.ok) return null;
-      const raw = await versionRes.text();
-      if (isTemplate(raw)) return null;
-    } finally {
-      clearTimeout(versionTimer);
-    }
-    return source;
+    return await createUrlSource(`${RAW_GITHUB}/${tag}/${TEMPLATE_SUBPATH}`, { stable: true });
   } catch {
     return null;
   }
 }
 
+async function resolveUpdateSource(explicitSource) {
+  if (explicitSource) {
+    return createUrlSource(explicitSource, { stable: false });
+  }
+
+  const errors = [];
+  try {
+    return await createNpmSource('latest');
+  } catch (e) {
+    errors.push(`npm latest: ${e.message}`);
+  }
+
+  const releaseSource = await resolveGithubReleaseSource();
+  if (releaseSource) return releaseSource;
+  errors.push('GitHub latest release: unavailable');
+
+  try {
+    return await createUrlSource(DEFAULT_SOURCE_BASE, { stable: false });
+  } catch (e) {
+    errors.push(`GitHub canonical main: ${e.message}`);
+  }
+
+  try {
+    return await createUrlSource(LEGACY_SOURCE_BASE, { stable: false });
+  } catch (e) {
+    errors.push(`GitHub legacy mirror: ${e.message}`);
+  }
+
+  const err = new Error('Cannot reach npm, canonical GitHub, or legacy mirror update sources.');
+  err.sourceErrors = errors;
+  throw err;
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const apply = args.includes('--apply');
@@ -240,14 +539,16 @@ async function main() {
   const acceptTemplate = readRepeatedFlagValues(args, '--accept-template');
   const ignoreVersion = args.includes('--ignore-version') || args.includes('--force-check');
   const explicitSource = readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE;
-  let sourceBase = normalizeSourceBase(explicitSource || DEFAULT_SOURCE_BASE);
-  let stableTagResolved = false;
-  if (!explicitSource) {
-    const resolved = await resolveStableSourceBase();
-    if (resolved) {
-      sourceBase = normalizeSourceBase(resolved);
-      stableTagResolved = true;
-    }
+  let source;
+  let sourceBase;
+  let sourceStable = false;
+  let sourceErrors = [];
+  try {
+    source = await resolveUpdateSource(explicitSource);
+    sourceBase = source.label;
+    sourceStable = Boolean(source.stable);
+  } catch (e) {
+    sourceErrors = e.sourceErrors || [e.message];
   }
 
   // 1. Read local state
@@ -302,44 +603,29 @@ async function main() {
 
   const localChecksums = localVersion.checksums || {};
 
-  // 2. Fetch remote version file
-  let remoteVersion;
-  try {
-    const raw = await fetchRemote(sourceBase + '.harness-version');
-    if (isTemplate(raw)) {
-      if (jsonOut) {
-        console.log(JSON.stringify({ status: 'template-remote', message: 'Remote .harness-version has not been generated yet.' }));
-      } else {
-        console.log('WARN: Remote .harness-version is a template (contains {{placeholders}}).');
-        console.log('  The generate step has not been run on the remote repo. No update possible.');
-        console.log('  This is expected during development; the update mechanism works once the remote is live.');
-      }
-      process.exitCode = 1;
-      return;
-    }
-    remoteVersion = JSON.parse(raw);
-  } catch (e) {
+  // 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) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'offline', message: 'Cannot reach GitHub.' }));
+      console.log(JSON.stringify({
+        status: 'offline',
+        message: 'Cannot reach npm, canonical GitHub, or legacy mirror update sources.',
+        sourceErrors,
+      }));
     } else {
-      console.error('ERROR: Cannot reach GitHub or invalid JSON. Offline?');
-      console.error(e.message);
+      console.error('ERROR: Cannot reach npm, canonical GitHub, or legacy mirror update sources. Offline?');
+      for (const err of sourceErrors) console.error(`  ${err}`);
     }
     process.exitCode = 1;
     return;
   }
 
-  // Compare versions and prevent downgrades from explicit custom sources.
-  function parseSemver(v) {
-    if (!v || typeof v !== 'string') return [0, 0, 0];
-    return v.replace(/^[^0-9]*/, '').split('.').slice(0, 3).map(n => Number(n) || 0);
-  }
-  function cmpSemver(a, b) {
-    const va = parseSemver(a), vb = parseSemver(b);
-    for (let i = 0; i < 3; i++) { if ((va[i]||0) > (vb[i]||0)) return 1; if ((va[i]||0) < (vb[i]||0)) return -1; }
-    return 0;
-  }
-
   const localGen = localVersion.generator || '0.0.0';
   const remoteGen = remoteVersion.generator || '0.0.0';
 
@@ -355,7 +641,7 @@ async function main() {
   const versionCmp = cmpSemver(remoteGen, localGen);
 
   if (!ignoreVersion && versionCmp <= 0) {
-    const reportDowngrade = !stableTagResolved;
+    const reportDowngrade = !sourceStable;
     if (jsonOut) {
       console.log(JSON.stringify({
         status: (versionCmp < 0 && reportDowngrade) ? 'downgrade-refused' : 'up-to-date',
@@ -378,6 +664,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. */
@@ -385,13 +683,37 @@ async function main() {
     return remoteSources[file] || file;
   }
 
+  async function fetchSourceFile(templateRelPath) {
+    if (source.kind === 'npm') return readNpmFile(source.package, templateRelPath);
+    return fetchRemote(source.base + templateRelPath);
+  }
+
+  function sourceUrl(templateRelPath) {
+    if (source.kind === 'npm') return `${source.label}${templateRelPath}`;
+    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);
     return {
       ...entry,
       templateHint,
-      remoteUrl: sourceBase + templateHint,
+      remoteUrl: sourceUrl(templateHint),
     };
   }
 
@@ -419,6 +741,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),
     };
   }
@@ -438,8 +761,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,
@@ -459,7 +786,7 @@ async function main() {
     const dest = safePath(file);
     if (!dest) throw new Error(`Traversal rejected: ${file}`);
     if (existsSync(dest) && lstatSync(dest).isSymbolicLink()) throw new Error(`Symlink rejected: ${file}`);
-    const content = await fetchRemote(sourceBase + remotePath(file));
+    const content = await fetchSourceFile(remotePath(file));
     const normalized = content.replace(/\r\n/g, '\n');
     const fetchedHash = sha256(normalized);
     if (fetchedHash !== remoteHash) throw new Error(`Hash mismatch: ${file}`);
@@ -490,12 +817,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();
@@ -517,10 +850,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);
@@ -533,6 +867,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' });
@@ -542,8 +917,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;
     }
 
@@ -555,16 +933,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 });
       }
@@ -579,7 +963,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({
@@ -592,7 +976,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' });
@@ -604,7 +988,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({
@@ -612,7 +996,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',
       });
@@ -628,11 +1012,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.
@@ -643,7 +1029,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) {
@@ -658,10 +1045,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('');
   }
 
@@ -678,56 +1066,87 @@ async function main() {
       console.log(`Applying SAFE/NEW files only; ${plan.conflict.length} conflicts will remain for AI/user merge.`);
     }
 
-    const lexists = existsSync;
-    let applied = 0;
+    const preparedWrites = [];
     let failed = 0;
 
-    for (const u of plan.updated) {
+    async function prepareWrite(entry, { mustNotExist = false } = {}) {
       try {
-        const dest = safePath(u.file);
-        if (!dest) { console.error(`   x Traversal rejected: ${u.file}`); failed++; continue; }
+        const dest = safePath(entry.file);
+        if (!dest) return { ok: false, message: `   x Traversal rejected: ${entry.file}` };
         // Symlink rejection: do not follow symlinks.
-        if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${u.file}`); failed++; continue; } } catch (_) {}
+        if (existsSync(dest)) {
+          try { if (lstatSync(dest).isSymbolicLink()) return { ok: false, message: `   x Symlink rejected: ${entry.file}` }; } catch (_) {}
+          if (mustNotExist) {
+            return { ok: false, message: `   x File created since plan: ${entry.file} - treating as CONFLICT` };
+          }
         }
-        const content = await fetchRemote(sourceBase + remotePath(u.file));
+        const content = await fetchSourceFile(remotePath(entry.file));
         const normalized = content.replace(/\r\n/g, '\n');
         const fetchedHash = sha256(normalized);
-        if (fetchedHash !== u.remoteHash) {
-          console.error(`   x Hash mismatch: ${u.file}`);
-          failed++; continue;
+        if (fetchedHash !== entry.remoteHash) {
+          return { ok: false, message: `   x Hash mismatch: ${entry.file}` };
         }
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, normalized, 'utf-8');
-        applied++;
+        return { ok: true, prepared: { file: entry.file, dest, content: normalized, mustNotExist } };
       } catch (e) {
-        console.error(`   x Failed: ${u.file} - ${e.message}`);
+        return { ok: false, message: `   x Failed: ${entry.file} - ${e.message}` };
+      }
+    }
+
+    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++;
       }
     }
 
-    for (const c of plan.created) {
+    if (failed === 0) {
+      for (const prepared of preparedWrites) {
+        if (prepared.mustNotExist && existsSync(prepared.dest)) {
+          console.error(`   x File created since plan: ${prepared.file} - treating as CONFLICT`);
+          failed++;
+        }
+      }
+    }
+
+    // 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 {
-        const dest = safePath(c.file);
-        if (!dest) { console.error(`   x Traversal rejected: ${c.file}`); failed++; continue; }
-        // TOCTOU: recheck file didn't appear since planning
-        if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${c.file}`); failed++; continue; } } catch (_) {}
-          console.error(`   x File created since plan: ${c.file} - treating as CONFLICT`);
-          failed++; continue;
+        for (const prepared of preparedWrites) {
+          mkdirSync(dirname(prepared.dest), { recursive: true });
+          writeFileSync(prepared.dest, prepared.content, 'utf-8');
+          applied++;
         }
-        const content = await fetchRemote(sourceBase + remotePath(c.file));
-        const normalized = content.replace(/\r\n/g, '\n');
-        const fetchedHash = sha256(normalized);
-        if (fetchedHash !== c.remoteHash) {
-          console.error(`   x Hash mismatch: ${c.file}`);
-          failed++; continue;
+        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);
         }
-        mkdirSync(dirname(dest), { recursive: true });
-        writeFileSync(dest, normalized, 'utf-8');
-        applied++;
       } catch (e) {
-        console.error(`   x Failed: ${c.file} - ${e.message}`);
+        console.error(`   x Failed while writing prepared files - ${e.message}`);
         failed++;
       }
     }
@@ -739,24 +1158,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.`);
@@ -765,8 +1203,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');
       }
@@ -784,9 +1222,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.');