@cassiomc1/forgeloop 0.1.8 → 0.1.9

package/LOOP_ENGINEERING.md

@@ -323,7 +323,11 @@ observed in the target. New targets receive canonical documents under
 `.forgeloop/kit/`; root `AGENTS.md`, `CLAUDE.md`, Cursor, and Copilot files are
 minimal native shims. `forgeloop update` migrates unchanged managed legacy root
 files, preserves modified or unowned files, and reports conflicts without
-following symlinks or escaping the selected target.
+following symlinks or escaping the selected target. Migration validates the
+complete plan, writes and verifies hidden destinations, atomically switches the
+manifest authority, and then cleans only legacy files whose recorded ownership
+hash still matches. `doctor` reports `E_MIGRATION_INCOMPLETE` for an interrupted
+authority switch or cleanup; a later `update` may safely resume that cleanup.
 
 ## Completion validation and chronology
 

package/README.md

@@ -59,6 +59,13 @@ flowchart TB
   root["FORGELOOP"]
 
   root --> entry["native adapters<br/>+ .forgeloop/kit/"]
+  entry --> migration{"target<br/>layout"}
+  migration -->|legacy v1| plan["validate paths<br/>+ build plan"]
+  plan --> hidden["write + verify<br/>hidden kit"]
+  hidden --> authority["atomic manifest<br/>authority switch"]
+  authority --> cleanup["hash-checked<br/>legacy cleanup"]
+  cleanup --> recovered["healthy or<br/>recoverable"]
+  migration -->|layout v2| retry["update + retry<br/>owned cleanup"]
   entry --> discovery["discovery +<br/>project profile"]
   discovery --> contract["current<br/>contract"]
   contract --> routing["deterministic<br/>route"]
@@ -97,6 +104,7 @@ flowchart TB
 
   classDef root fill:#08090C,stroke:#6E6AF5,stroke-width:3px,color:#EDEEF0;
   classDef entry fill:#101218,stroke:#3EDBB8,stroke-width:2px,color:#EDEEF0;
+  classDef migration fill:#0F766E,stroke:#5EEAD4,stroke-width:2px,color:#FFFFFF;
   classDef routing fill:#4F46E5,stroke:#A5B4FC,stroke-width:2px,color:#FFFFFF;
   classDef state fill:#373A46,stroke:#A1A1AA,stroke-width:2px,color:#FFFFFF;
   classDef evidence fill:#3EDBB8,stroke:#99F6E4,stroke-width:2px,color:#08090C;
@@ -107,6 +115,7 @@ flowchart TB
 
   class root root;
   class entry,discovery,delegation entry;
+  class migration,plan,hidden,authority,cleanup,recovered,retry migration;
   class routing,preflight,ready routing;
   class state,events,lifecycle state;
   class checks,receipt,audit evidence;
@@ -118,6 +127,9 @@ flowchart TB
 ```
 
 Equivalent reading for text-only environments: adapters load the canonical kit;
+an older target follows validate paths → write and verify hidden files → switch
+manifest authority → hash-checked cleanup, while an interrupted migration is
+diagnosed and retried by `doctor`/`update`;
 discovery creates the contract and deterministic route; contract, route, and
 required gates must produce `PREFLIGHT_READY` before the resumable state and
 append-only event ledger authorize the lifecycle. Verification produces
@@ -145,7 +157,12 @@ project without overwriting local instructions. When the package is available
 in the npm registry, use the commands below; otherwise use the repository
 checkout fallback.
 
+The current published release is `@cassiomc1/forgeloop@0.1.9`.
+Pin this version when a reproducible blind run or release-identity check is
+required:
+
 ```bash
+npx @cassiomc1/forgeloop@0.1.9 --version
 npx @cassiomc1/forgeloop init
 npx @cassiomc1/forgeloop doctor
 npx @cassiomc1/forgeloop update
@@ -327,8 +344,17 @@ node src/cli.js update
 The release workflow uses [npm trusted publishing](https://docs.npmjs.com/trusted-publishers)
 through GitHub Actions OIDC. Before the first release, register this repository
 and workflow as the package's trusted publisher in npm; each `vX.Y.Z` tag must
-match `package.json`. After publishing, verify the package version and its npm
-provenance record.
+match `package.json`. After publishing, verify the complete immutable release
+identity before a blind run:
+
+```bash
+RELEASE_COMMIT="$(git rev-list -n1 vX.Y.Z)"
+npm run release:identity -- --version X.Y.Z --release-commit "$RELEASE_COMMIT"
+```
+
+Only `RELEASE_IDENTITY_VALID` is sufficient. The read-only check compares the
+release commit and GitHub tag with npm's version, `gitHead`, tarball URL,
+SHA-1, and SHA-512 integrity; it never publishes or changes a tag.
 
 The commands above use the current directory. To install into another existing
 project directory, pass a relative or absolute `--path`:
@@ -360,7 +386,12 @@ reference.
 Targets created by an older package layout are migrated by `update`: unchanged
 managed root files move into the hidden kit, while modified or unowned root
 files are preserved and reported as conflicts. The migration never follows a
-symlink or deletes a file whose managed hash no longer matches.
+symlink or deletes a file whose managed hash no longer matches. The migration
+writes and verifies the complete hidden plan, atomically switches the manifest
+authority, and only then cleans owned legacy files. If a process stops between
+those stages, `doctor` reports `E_MIGRATION_INCOMPLETE` and the next `update`
+retries cleanup only when the recorded legacy hash still matches; modified or
+unowned files remain for manual review.
 
 ### Migrate an existing mdfiles installation
 

package/THREAT_MODEL.md

@@ -12,7 +12,7 @@ remaining trust boundaries and their executable evidence.
 | --- | --- | --- | --- | --- | --- |
 | Path traversal | Writes or reads outside the selected target | Target path and every managed relative path | `ensureWithin`, safe-path checks, realpath containment, Windows-drive rejection | A separately privileged process can change the filesystem after validation | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/path-traversal.json` |
 | Symlink escape | Redirects a managed path to another directory | Existing target parents and artifact paths | Reject symlinked targets, parents, and destinations before access | The check is not a filesystem lock | `tests/core.test.js`, `tests/portability.test.js`, `tests/fixtures/protocol/invalid/symlink-target.json` |
-| Malicious manifest | Causes unsafe update or false ownership claims | `.forgeloop/manifest.json` | Schema, hash, safe-path, and preserve-flag validation; conflicts remain visible | A trusted operator can still deliberately edit the manifest | `tests/cli.test.js`, `tests/core.test.js` |
+| Malicious manifest | Causes unsafe update or false ownership claims | `.forgeloop/manifest.json` | Schema, managed/legacy hash, safe-path, and preserve-flag validation; incomplete migration remains visible | A trusted operator can still deliberately edit the manifest | `tests/cli.test.js`, `tests/core.test.js`, `tests/hidden-layout.test.js` |
 | Malicious work-state | Resumes stale, secret-bearing, or invalid work | `.forgeloop/work-state.json` | Schema/semantic checks, version checks, transition checks, contract/HEAD/artifact freshness, secret scan, size/depth bounds | Freshness cannot prove that an external process did not alter a file immediately afterward | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, `tests/security-limits.test.js` |
 | Forged preparation | Makes an agent's prose claim look like a completed preflight | Contract, route, gate, and preflight artifacts | Canonical SHA-256 fingerprints, guide-declared gate requirements, stale-artifact checks, and `E_*` failures | The CLI cannot stop a separate process from writing project files before preflight | `tests/protocol-artifacts.test.js`, `tests/preflight.test.js` |
 | Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |

package/conformance/README.md

@@ -4,6 +4,10 @@ These scenarios are adapter-facing contracts. They describe requests and the
 artifacts a live agent must produce; they do not invoke a model runtime and are
 not part of the deterministic `npm test` execution path.
 
+The current published baseline for new runs is
+`@cassiomc1/forgeloop@0.1.9`. Pin that version when preparing a reproducible
+blind run; historical reports retain the exact package version they used.
+
 Run a scenario in a disposable target using the Standard profile first:
 
 ```bash
@@ -43,6 +47,34 @@ diagnostic records belong under [`conformance/runs/`](./runs/); they must not
 contain secrets, credentials, hidden reasoning, or unnecessary conversation
 history.
 
+## Release identity evidence
+
+Every live-run report records the exact published package used by the target.
+Include all of these fields before sending the blind prompt:
+
+```text
+package: @cassiomc1/forgeloop@X.Y.Z
+npm gitHead: <40-character commit SHA>
+release commit: <40-character commit SHA>
+GitHub tag: vX.Y.Z -> <40-character commit SHA>
+tarball URL: https://registry.npmjs.org/...
+tarball SHA-1: <40-character hex digest>
+npm SHA-512 integrity: sha512-<base64 digest>
+release identity: RELEASE_IDENTITY_VALID
+```
+
+Run the repository's read-only verifier against the exact release commit:
+
+```bash
+RELEASE_COMMIT="$(git rev-list -n1 vX.Y.Z)"
+npm run release:identity -- --version X.Y.Z --release-commit "$RELEASE_COMMIT"
+```
+
+Do not interpret a local package version, a green build, or a tarball URL by
+itself as publication proof. If the verifier cannot establish every identity
+field, record `RELEASE_IDENTITY_NOT_VERIFIED` or
+`RELEASE_IDENTITY_INVALID` and do not start the blind run.
+
 The complete-website scenario deliberately fails when implementation starts
 before the contract, route, and required gates exist.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Portable, verifiable instruction kit for AI agents and developers",
   "repository": {
     "type": "git",
@@ -47,6 +47,7 @@
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
-    "pack:check": "node --test tests/package.test.js"
+    "pack:check": "node --test tests/package.test.js",
+    "release:identity": "node scripts/verify_release_identity.mjs"
   }
 }

package/src/commands/doctor.js

@@ -147,6 +147,23 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     }
     const hasLegacyAlternative = layoutVersion >= LAYOUT_VERSION
       && entry.legacyRelativePath !== entry.relativePath;
+    if (layoutVersion < LAYOUT_VERSION && entry.legacyRelativePath !== entry.relativePath) {
+      const hiddenDestination = ensureWithin(target, entry.relativePath);
+      try {
+        await assertSafePath(target, entry.relativePath);
+        if (await fileExists(hiddenDestination)) {
+          findings.push(finding(
+            "E_MIGRATION_INCOMPLETE",
+            "error",
+            entry.relativePath,
+            "A hidden migration destination exists while the legacy manifest is still authoritative; rerun forgeloop update to recover the transaction.",
+            "Run forgeloop update and inspect the result before changing either copy.",
+          ));
+        }
+      } catch (error) {
+        findings.push(finding("unsafe-path", "error", entry.relativePath, error.message));
+      }
+    }
     if (hasLegacyAlternative) {
       try {
         await assertSafePath(target, entry.legacyRelativePath);
@@ -161,10 +178,11 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
         : null;
       if (legacyDestination && await fileExists(legacyDestination)) {
         findings.push(finding(
-          "legacy-root-file",
-          "warning",
+          "E_MIGRATION_INCOMPLETE",
+          "error",
           entry.legacyRelativePath,
-          "Canonical file remains in the legacy root layout; run forgeloop update to migrate it safely.",
+          "Canonical file remains in the legacy root layout; migration is incomplete and the legacy copy was preserved.",
+          "Run forgeloop update; it removes the root copy only when the recorded ownership hash still matches.",
         ));
         continue;
       }
@@ -215,10 +233,24 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
       if (await fileExists(legacyPath)) {
         if (entry.sourcePath !== "PROJECT_PROFILE.md") {
           findings.push(finding(
-            "legacy-root-file",
-            "warning",
+            "E_MIGRATION_INCOMPLETE",
+            "error",
+            entry.legacyRelativePath,
+            record.legacySha256
+              ? "A legacy root copy remains after the manifest authority switch; cleanup is incomplete."
+              : "A legacy root copy remains without an ownership proof; it was preserved.",
+            "Run forgeloop update; modified or unowned legacy files require manual review and are never deleted silently.",
+          ));
+        }
+        if (entry.sourcePath === "PROJECT_PROFILE.md") {
+          findings.push(finding(
+            "E_MIGRATION_INCOMPLETE",
+            "error",
             entry.legacyRelativePath,
-            "A legacy root copy remains alongside the canonical hidden kit; review it after migration.",
+            record.legacySha256
+              ? "The legacy project profile remains after the manifest authority switch; cleanup is incomplete."
+              : "A legacy project profile remains alongside the hidden canonical profile.",
+            "Run forgeloop update, then remove the root profile only after verifying ownership and preserved bytes.",
           ));
         }
       }

package/src/commands/update.js

@@ -43,6 +43,10 @@ async function removeEmptyLegacyDirectory(target, relativePath, dryRun) {
 
 function addLegacyCleanup(cleanupFiles, cleanupDirectories, relativePath) {
   cleanupFiles.add(relativePath);
+  addLegacyCleanupDirectory(cleanupDirectories, relativePath);
+}
+
+function addLegacyCleanupDirectory(cleanupDirectories, relativePath) {
   for (const directory of LEGACY_CLEANUP_DIRECTORIES) {
     if (relativePath === directory || relativePath.startsWith(`${directory}/`)) {
       cleanupDirectories.add(directory);
@@ -50,7 +54,37 @@ function addLegacyCleanup(cleanupFiles, cleanupDirectories, relativePath) {
   }
 }
 
-async function migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries }) {
+function manifestRecord(sha256Value, preserve, legacySha256Value = null) {
+  return {
+    sha256: sha256Value,
+    preserve,
+    ...(legacySha256Value ? { legacySha256: legacySha256Value } : {}),
+  };
+}
+
+async function notifyStage(hooks, stage, context) {
+  if (typeof hooks?.afterStage === "function") await hooks.afterStage(stage, context);
+}
+
+async function cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks }) {
+  for (const relativePath of cleanupFiles) {
+    await assertSafePath(target, relativePath);
+    if (typeof hooks?.beforeCleanup === "function") {
+      await hooks.beforeCleanup(relativePath);
+    }
+    const legacyPath = ensureWithin(target, relativePath);
+    if (!dryRun && await fileExists(legacyPath)) await unlink(legacyPath);
+  }
+
+  for (const relativePath of cleanupDirectories) {
+    if (typeof hooks?.beforeCleanupDirectory === "function") {
+      await hooks.beforeCleanupDirectory(relativePath);
+    }
+    await removeEmptyLegacyDirectory(target, relativePath, dryRun);
+  }
+}
+
+async function migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks = {} }) {
   const nextManifest = createManifest(packageVersion);
   const actions = [];
   const conflicts = [];
@@ -86,6 +120,11 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
 
       const currentBytes = await readBytes(destination);
       const currentHash = sha256(currentBytes);
+      if (legacyRecord && currentHash === sourceHash) {
+        actions.push({ action: "skip", path: entry.relativePath, reason: "current-shim" });
+        nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, false);
+        continue;
+      }
       if (legacyRecord && currentHash === legacyRecord.sha256) {
         if (currentHash === sourceHash) {
           actions.push({ action: "skip", path: entry.relativePath, reason: "current-shim" });
@@ -114,32 +153,67 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
     if (destinationExists) {
       const currentBytes = await readBytes(destination);
       const currentHash = sha256(currentBytes);
-      if (!destinationRecord && currentHash !== sourceHash && entry.sourcePath !== PROFILE_PATH) {
+      const hiddenMatchesSource = currentHash === sourceHash;
+      const legacyBytes = legacyExists ? await readBytes(legacyDestination) : null;
+      const legacyHash = legacyBytes ? sha256(legacyBytes) : null;
+      const unchangedManagedLegacy = Boolean(legacyRecord) && legacyHash === legacyRecord.sha256;
+
+      if (entry.sourcePath === PROFILE_PATH
+        && legacyExists
+        && legacyRecord
+        && currentHash === legacyHash) {
+        actions.push({ action: "skip", path: entry.relativePath, reason: "profile-move-resumed" });
+        addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+        nextManifest.files[entry.relativePath] = manifestRecord(currentHash, true, legacyHash);
+        continue;
+      }
+
+      if (!hiddenMatchesSource && !destinationRecord && entry.sourcePath !== PROFILE_PATH) {
         conflicts.push(migrationConflict(
           "E_HIDDEN_KIT_MIGRATION_CONFLICT",
           entry.relativePath,
           "Existing hidden kit file is unmanaged and was not overwritten.",
         ));
         addAction(actions, dryRun, "preserve-conflict", entry.relativePath, { reason: "hidden-unmanaged" });
+      } else if (hiddenMatchesSource && legacyExists && unchangedManagedLegacy) {
+        actions.push({ action: "skip", path: entry.relativePath, reason: "hidden-ready" });
+        addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+        nextManifest.files[entry.relativePath] = manifestRecord(
+          sourceHash,
+          entry.sourcePath === PROFILE_PATH,
+          legacyHash,
+        );
+        continue;
+      } else if (hiddenMatchesSource && legacyExists) {
+        const conflict = entry.sourcePath === PROFILE_PATH
+          ? migrationConflict(
+            "E_PROFILE_MIGRATION_CONFLICT",
+            entry.legacyRelativePath,
+            "A legacy project profile remains beside the hidden kit without a matching managed hash; both copies were preserved.",
+          )
+          : migrationConflict(
+            "E_LEGACY_FILE_MIGRATION_CONFLICT",
+            entry.legacyRelativePath,
+            "A legacy file remains beside the hidden kit without a matching managed hash; it was preserved.",
+          );
+        conflicts.push(conflict);
+        addAction(actions, dryRun, "preserve-conflict", entry.legacyRelativePath, { reason: "legacy-residual" });
       } else {
         actions.push({ action: "skip", path: entry.relativePath, reason: "already-present" });
       }
-      nextManifest.files[entry.relativePath] = {
-        sha256: currentHash,
-        preserve: entry.sourcePath === PROFILE_PATH
+      nextManifest.files[entry.relativePath] = manifestRecord(
+        currentHash,
+        entry.sourcePath === PROFILE_PATH
           || !destinationRecord
           || Boolean(destinationRecord.preserve),
-      };
+      );
       continue;
     }
 
     if (!legacyExists) {
       addAction(actions, dryRun, "create", entry.relativePath);
       writes.push({ destination, bytes: entry.bytes });
-      nextManifest.files[entry.relativePath] = {
-        sha256: sourceHash,
-        preserve: entry.sourcePath === PROFILE_PATH,
-      };
+      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
       continue;
     }
 
@@ -150,24 +224,24 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
     if (entry.sourcePath === PROFILE_PATH && legacyRecord) {
       addAction(actions, dryRun, "move-profile", entry.legacyRelativePath, { to: entry.relativePath });
       writes.push({ destination, bytes: legacyBytes });
-      if (!dryRun) addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
-      nextManifest.files[entry.relativePath] = { sha256: legacyHash, preserve: true };
+      addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+      nextManifest.files[entry.relativePath] = manifestRecord(legacyHash, true, legacyHash);
       continue;
     }
 
     if (legacyRecord?.preserve && unchangedManaged) {
       addAction(actions, dryRun, "move-preserved", entry.legacyRelativePath, { to: entry.relativePath });
       writes.push({ destination, bytes: legacyBytes });
-      if (!dryRun) addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
-      nextManifest.files[entry.relativePath] = { sha256: legacyHash, preserve: true };
+      addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+      nextManifest.files[entry.relativePath] = manifestRecord(legacyHash, true, legacyHash);
       continue;
     }
 
     if (unchangedManaged) {
       addAction(actions, dryRun, "migrate", entry.legacyRelativePath, { to: entry.relativePath });
       writes.push({ destination, bytes: entry.bytes });
-      if (!dryRun) addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
-      nextManifest.files[entry.relativePath] = { sha256: sourceHash, preserve: false };
+      addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, false, legacyHash);
       continue;
     }
 
@@ -190,35 +264,28 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
       reason: legacyRecord ? "managed-modified" : "unmanaged",
     });
     writes.push({ destination, bytes: entry.bytes });
-    nextManifest.files[entry.relativePath] = {
-      sha256: sourceHash,
-      preserve: entry.sourcePath === PROFILE_PATH,
-    };
+    nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
   }
 
-  // Apply all hidden writes and verify their bytes before removing any legacy file.
+  // Apply all hidden writes and verify their bytes before changing manifest authority.
   for (const plan of writes) {
     await writeFileAtomic(plan.destination, plan.bytes, { dryRun });
     if (!dryRun) await verifyWrite(plan.destination, plan.bytes);
   }
+  await notifyStage(hooks, "HIDDEN_WRITTEN", { writes: writes.length });
+  await notifyStage(hooks, "HIDDEN_VERIFIED", { writes: writes.length });
 
-  for (const relativePath of cleanupFiles) {
-    await assertSafePath(target, relativePath);
-    const legacyPath = ensureWithin(target, relativePath);
-    if (!dryRun && await fileExists(legacyPath)) await unlink(legacyPath);
-  }
-
-  for (const relativePath of cleanupDirectories) {
-    await removeEmptyLegacyDirectory(target, relativePath, dryRun);
-  }
-
-  // The manifest is written last so layoutVersion 2 is never authoritative before
-  // hidden destinations and adapter decisions have been applied.
+  // Atomic manifest replacement is the authority switch. Cleanup follows it and
+  // remains recoverable because managed legacy hashes are retained in the record.
   await writeManifest(target, nextManifest, { dryRun });
+  await notifyStage(hooks, "MANIFEST_SWITCHED", { cleanupFiles: [...cleanupFiles] });
+  await cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks });
+  await notifyStage(hooks, "LEGACY_CLEANED", { cleanupFiles: [...cleanupFiles] });
+  await notifyStage(hooks, "COMPLETE", { cleanupFiles: [...cleanupFiles] });
   return { actions, conflicts, manifest: nextManifest };
 }
 
-export async function runUpdate({ target, dryRun, packageRoot, packageVersion }) {
+export async function runUpdate({ target, dryRun, packageRoot, packageVersion, hooks = {} }) {
   const currentManifest = await readManifest(target);
   if (!currentManifest) {
     throw new Error("No .forgeloop/manifest.json found; run forgeloop init first.");
@@ -226,13 +293,15 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
 
   const entries = await readTemplateEntries(packageRoot);
   if ((currentManifest.layoutVersion ?? 1) < LAYOUT_VERSION) {
-    return migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries });
+    return migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks });
   }
 
   const nextManifest = structuredClone(currentManifest);
   const actions = [];
   const conflicts = [];
   const plans = [];
+  const cleanupFiles = new Set();
+  const cleanupDirectories = new Set();
   const pruneActions = [];
   const shippedPaths = new Set(entries.map((entry) => entry.relativePath));
 
@@ -249,10 +318,34 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
   for (const entry of entries) {
     const destination = ensureWithin(target, entry.relativePath);
     await assertSafePath(target, entry.relativePath);
+    const hasLegacyAlternative = entry.legacyRelativePath !== entry.relativePath;
+    const legacyDestination = hasLegacyAlternative
+      ? ensureWithin(target, entry.legacyRelativePath)
+      : null;
+    if (hasLegacyAlternative) await assertSafePath(target, entry.legacyRelativePath);
     const sourceHash = sha256(entry.bytes);
     const record = currentManifest.files[entry.relativePath];
     const exists = await fileExists(destination);
 
+    if (hasLegacyAlternative && record?.legacySha256) {
+      addLegacyCleanupDirectory(cleanupDirectories, entry.legacyRelativePath);
+    }
+    if (hasLegacyAlternative && await fileExists(legacyDestination)) {
+      const legacyHash = sha256(await readBytes(legacyDestination));
+      if (record?.legacySha256 && legacyHash === record.legacySha256) {
+        addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+      } else {
+        conflicts.push({
+          code: "E_LEGACY_FILE_MIGRATION_CONFLICT",
+          path: entry.legacyRelativePath,
+          message: record?.legacySha256
+            ? "Legacy file changed after the migration authority switch; it was preserved."
+            : "Legacy root file remains without ownership proof; it was preserved.",
+        });
+        actions.push({ action: "preserve-conflict", path: entry.legacyRelativePath, reason: "legacy-residual" });
+      }
+    }
+
     if (!exists) {
       plans.push({
         action: dryRun ? "would-create" : "created",
@@ -261,6 +354,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
         record: {
           sha256: sourceHash,
           preserve: entry.sourcePath === PROFILE_PATH,
+          ...(record?.legacySha256 ? { legacySha256: record.legacySha256 } : {}),
         },
       });
       continue;
@@ -318,5 +412,6 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
   nextManifest.packageName = PACKAGE_NAME;
   nextManifest.packageVersion = packageVersion;
   await writeManifest(target, nextManifest, { dryRun });
+  await cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks });
   return { actions, conflicts, manifest: nextManifest };
 }

package/src/core/manifest.js

@@ -49,6 +49,10 @@ function validateManifest(manifest) {
     if (typeof record.preserve !== "boolean") {
       throw new Error(`Invalid manifest preserve flag for ${relativePath}`);
     }
+    if (record.legacySha256 !== undefined
+      && (typeof record.legacySha256 !== "string" || !/^[a-f0-9]{64}$/.test(record.legacySha256))) {
+      throw new Error(`Invalid manifest legacy hash for ${relativePath}`);
+    }
   }
   return manifest;
 }