@cassiomc1/forgeloop 0.1.8 → 0.1.10

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,19 @@ 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 hidden<br/>kit"]
+  hidden --> verified["verify hidden<br/>bytes"]
+  verified --> authority["atomic manifest<br/>authority switch"]
+  authority --> cleanup["hash-checked<br/>legacy cleanup"]
+  cleanup --> recovered["healthy or<br/>recoverable"]
+  hidden -. interruption .-> incomplete["doctor: E_MIGRATION_INCOMPLETE"]
+  verified -. interruption .-> incomplete
+  authority -. interruption .-> incomplete
+  cleanup -. interruption .-> incomplete
+  migration -->|layout v2| retry["update + retry<br/>owned cleanup"]
+  incomplete --> retry
   entry --> discovery["discovery +<br/>project profile"]
   discovery --> contract["current<br/>contract"]
   contract --> routing["deterministic<br/>route"]
@@ -97,6 +110,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 +121,7 @@ flowchart TB
 
   class root root;
   class entry,discovery,delegation entry;
+  class migration,plan,hidden,verified,authority,cleanup,recovered,retry,incomplete migration;
   class routing,preflight,ready routing;
   class state,events,lifecycle state;
   class checks,receipt,audit evidence;
@@ -118,6 +133,11 @@ flowchart TB
 ```
 
 Equivalent reading for text-only environments: adapters load the canonical kit;
+an older target follows validate paths → write hidden files → verify their bytes
+→ switch manifest authority atomically → hash-checked cleanup. An interruption
+after hidden writes, after verification, after the authority switch, or during
+cleanup is diagnosed by `doctor` as `E_MIGRATION_INCOMPLETE` and retried by
+`update`; modified or unmanaged residual files remain preserved;
 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
@@ -138,6 +158,37 @@ Antigravity, OpenCode, Hermes, Pi, Command Code, and Freebuff use the shared
 documents; see [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md) for the
 official sources and precedence notes.
 
+### Migration recovery and release freeze
+
+Legacy layout migration keeps `.forgeloop/kit/` as the canonical layout and
+does not make `layoutVersion: 2` authoritative until every planned hidden file
+has been written and byte-verified. Cleanup runs only after the manifest switch
+and only for legacy files whose recorded ownership hash still matches when
+ForgeLoop revalidates it immediately before deletion. A modified, unmanaged,
+or `preserve=true` file is retained for manual review.
+
+The interruption vocabulary is test-only and is not a runtime state machine:
+
+```text
+VALIDATED → HIDDEN_WRITTEN → HIDDEN_VERIFIED → MANIFEST_SWITCHED
+          → LEGACY_CLEANED → COMPLETE
+```
+
+The regression suite injects failures at these boundaries and verifies that
+`doctor` explains the incomplete migration before a later `update` recovers
+owned cleanup. The frozen published installation under
+[`tests/fixtures/legacy-0.1.6/`](./tests/fixtures/legacy-0.1.6/) is derived
+from the real npm tarball, includes provenance and digests, and is copied into
+tests locally; CI does not download npm packages.
+
+The current published baseline for a reproducible blind run is
+`@cassiomc1/forgeloop@0.1.9`. The supplied hardening brief's `0.1.8` reference
+is historical; never move `v0.1.8` or `v0.1.9`, and use the read-only release
+identity verifier before a live run. The repository candidate is `0.1.10`, but
+it is not published: its completion-validation and cleanup TOCTOU fixes are not
+part of the frozen `0.1.9` tarball. Publish, tag, and repeat identity
+verification before a blind run that needs those executable changes.
+
 ### Use with npm
 
 The npm CLI targets Node.js 20 or newer and installs the kit into an existing
@@ -145,7 +196,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 +383,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 +425,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,8 @@ 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` |
+| Interrupted or concurrent migration cleanup | Leaves a new hidden kit, an old manifest, residual legacy files, or mutates a legacy file after planning | Hidden kit, manifest authority, and legacy root cleanup | Validate all paths, write and verify the hidden plan, atomically switch authority, then revalidate safe paths and recorded ownership hashes immediately before unlink; mismatches are preserved and `doctor` reports `E_MIGRATION_INCOMPLETE` | Hash-before-unlink narrows but cannot eliminate the final OS-level race without filesystem locking; a separately privileged process remains outside the trust boundary | `tests/hidden-layout.test.js`, `README.md` |
 | 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` |
@@ -23,6 +24,7 @@ remaining trust boundaries and their executable evidence.
 | Artifact content exposure | Sensitive material enters portable artifacts or diagnostics | State, receipt, delegation, evidence, and repository text | Nested key/value detection, shaped marker patterns, scanner coverage, no content echo in errors | Content scanners cannot prove that an unknown encoding is harmless | `tests/security-limits.test.js`, `tests/test_scan_secrets.py`, `scripts/scan_secrets.py` |
 | Stale checkpoint replay | Repeats work against a changed contract or material file | Resume boundary between a saved state and current target | Contract fingerprint, repository fingerprint, required-artifact hashes, protocol version, and conservative revalidation | A contract author must provide the current contract file for comparison | `tests/checkpoint-freshness.test.js`, `tests/cli.test.js` |
 | Unsafe publication claim | Local output is mistaken for push, PR, merge, or deployment | Receipt publication fields and evidence | Publication starts false; each true claim requires matching evidence; no CLI publication action | Remote provider state is outside local verification | `tests/receipt-semantics.test.js`, `README.md` |
+| Release identity drift | A blind run uses a package whose code, tag, commit, or tarball digest differs from the stated release | npm metadata, GitHub tag, and release commit | Read-only verifier requires package version, `gitHead`, tag, tarball URL, SHA-1, and SHA-512 to agree before the prompt starts | Registry and remote state require a fresh check for every release; a documentation commit is not a new npm package | `tests/release-identity.test.js`, `scripts/verify_release_identity.mjs`, `conformance/README.md` |
 | Schema confusion | A malformed or altered schema is treated as available | Shipped and target-local `schemas/` directory | Health checks parse every schema and classify valid, missing, invalid, or unsupported-version | Schema health does not replace review of semantic relationships | `tests/schema-health.test.js`, `src/core/schema-validation.js` |
 | Protocol-version confusion | Old/future artifacts are silently reinterpreted | Cross-artifact protocol boundary | Explicit v1 checks and conformance errors for unsupported or mixed versions | A future protocol needs a deliberate migration implementation | `tests/conformance.test.js`, `tests/fixtures/protocol/invalid/` |
 | Dependency-cycle denial of service | Coordination cannot make progress or spends unbounded work | Delegation dependency graph | Deterministic DFS cycle detection, unknown-reference rejection, and bounded JSON | A caller can still submit many valid tasks; host-level quotas remain external | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
@@ -32,6 +34,9 @@ remaining trust boundaries and their executable evidence.
 
 - Safe paths are checked before reading or writing; no protocol field is a
   shell command.
+- A migration never treats `layoutVersion: 2` as authoritative before the
+  hidden kit is complete and verified; cleanup follows the authority switch and
+  is limited by recorded ownership hashes.
 - A `NOT_VERIFIED` or `BLOCKED` evidence record is never upgraded to observed
   success by a formatter.
 - Local checks do not imply remote publication, merge, deployment, or provider

package/conformance/README.md

@@ -4,6 +4,30 @@ 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.
+
+The frozen baseline was verified on 2026-08-13 with this identity:
+
+```text
+package: @cassiomc1/forgeloop@0.1.9
+npm gitHead: 0e48240894671ecda2458b15671020b0a7255e70
+release commit: 0e48240894671ecda2458b15671020b0a7255e70
+GitHub tag: v0.1.9 -> 0e48240894671ecda2458b15671020b0a7255e70
+tarball URL: https://registry.npmjs.org/@cassiomc1/forgeloop/-/forgeloop-0.1.9.tgz
+tarball SHA-1: fef7587ebd878e845e9746b4d049a6fe6ef333c5
+npm SHA-512 integrity: sha512-sCvPEDOYT1svNnA8+zw57dJ97N6sNCUH8eDbM6f3cS6eXLCIFFXRPkCAASA+ZPu5mAKbcNaU1TaFKjojbL3DEA==
+release identity: RELEASE_IDENTITY_VALID
+```
+
+The repository may contain documentation or executable commits after this
+frozen package. Those commits do not change the package used by the blind run;
+the repository's `0.1.10` candidate includes completion-validation and cleanup
+TOCTOU fixes that are not in `0.1.9`. If a blind run needs those executable
+changes, publish and tag the candidate, then repeat the complete identity check
+before starting the run.
+
 Run a scenario in a disposable target using the Standard profile first:
 
 ```bash
@@ -43,9 +67,52 @@ 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.
 
+## Migration compatibility evidence
+
+The real published `0.1.6` fixture at
+[`tests/fixtures/legacy-0.1.6/`](../tests/fixtures/legacy-0.1.6/) is frozen
+with package, tarball, SHA-1, SHA-512, `gitHead`, and extraction-date metadata.
+The migration tests run from those local bytes and cover interruptions after
+hidden writes, after hidden verification, after the manifest authority switch,
+and during legacy cleanup. An interrupted target must be diagnosed as
+`E_MIGRATION_INCOMPLETE`; a later `update` may retry only hash-owned cleanup.
+User-modified, unmanaged, and `preserve=true` files remain untouched even when
+that leaves a root residual. ForgeLoop revalidates the recorded ownership hash
+immediately before deleting each managed legacy file. This narrows the race
+window but does not provide OS-level filesystem locking against a separately
+privileged concurrent process.
+
 ## Autonomous blind-run isolation
 
 External workflows may help with local planning, review, tests, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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

@@ -41,8 +41,12 @@ async function removeEmptyLegacyDirectory(target, relativePath, dryRun) {
   }
 }
 
-function addLegacyCleanup(cleanupFiles, cleanupDirectories, relativePath) {
-  cleanupFiles.add(relativePath);
+function addLegacyCleanup(cleanupFiles, cleanupDirectories, relativePath, expectedLegacySha256) {
+  cleanupFiles.set(relativePath, expectedLegacySha256);
+  addLegacyCleanupDirectory(cleanupDirectories, relativePath);
+}
+
+function addLegacyCleanupDirectory(cleanupDirectories, relativePath) {
   for (const directory of LEGACY_CLEANUP_DIRECTORIES) {
     if (relativePath === directory || relativePath.startsWith(`${directory}/`)) {
       cleanupDirectories.add(directory);
@@ -50,12 +54,53 @@ 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, actions, conflicts }) {
+  for (const [relativePath, expectedLegacySha256] of cleanupFiles) {
+    if (typeof hooks?.beforeCleanup === "function") {
+      await hooks.beforeCleanup(relativePath);
+    }
+    await assertSafePath(target, relativePath);
+    const legacyPath = ensureWithin(target, relativePath);
+    if (dryRun || !(await fileExists(legacyPath))) continue;
+    const currentLegacySha256 = sha256(await readBytes(legacyPath));
+    if (currentLegacySha256 !== expectedLegacySha256) {
+      conflicts.push(migrationConflict(
+        "E_LEGACY_FILE_MIGRATION_CONFLICT",
+        relativePath,
+        "Legacy file changed before cleanup; it was preserved.",
+      ));
+      actions.push({ action: "preserve-conflict", path: relativePath, reason: "changed-before-cleanup" });
+      continue;
+    }
+    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 = [];
   const writes = [];
-  const cleanupFiles = new Set();
+  const cleanupFiles = new Map();
   const cleanupDirectories = new Set();
 
   // Validate every path before creating the migration plan or touching data.
@@ -86,6 +131,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 +164,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, legacyHash);
+        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, legacyHash);
+        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 +235,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, legacyHash);
+      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, legacyHash);
+      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, legacyHash);
+      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, false, legacyHash);
       continue;
     }
 
@@ -190,35 +275,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.keys()] });
+  await cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks, actions, conflicts });
+  await notifyStage(hooks, "LEGACY_CLEANED", { cleanupFiles: [...cleanupFiles.keys()] });
+  await notifyStage(hooks, "COMPLETE", { cleanupFiles: [...cleanupFiles.keys()] });
   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 +304,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 Map();
+  const cleanupDirectories = new Set();
   const pruneActions = [];
   const shippedPaths = new Set(entries.map((entry) => entry.relativePath));
 
@@ -249,10 +329,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, record.legacySha256);
+      } 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 +365,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 +423,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, actions, conflicts });
   return { actions, conflicts, manifest: nextManifest };
 }

package/src/core/checks.js

@@ -92,24 +92,35 @@ export function assertCheckList(value, label = "checks") {
   return value;
 }
 
-export function requiredChecksSatisfied(checks, requiredIds, { allowInferred = false } = {}) {
+function requiredChecksSatisfiedBy(checks, requiredValues, selector, { allowInferred = false } = {}) {
   assertCheckList(checks);
-  if (!Array.isArray(requiredIds)) throw checkError("E_CHECK_INVALID", "requiredIds must be an array");
-  const byId = new Map(checks.map((check) => [check.id, check]));
+  if (!Array.isArray(requiredValues)) throw checkError("E_CHECK_INVALID", "required values must be an array");
   const errors = [];
-  for (const id of requiredIds) {
-    const check = byId.get(id);
+  for (const value of requiredValues) {
+    const candidates = checks.filter((check) => selector(check) === value);
+    const check = candidates.find((candidate) => candidate.status === "passed"
+      && (allowInferred || candidate.evidenceKind === "OBSERVED"))
+      ?? candidates.find((candidate) => candidate.status === "passed")
+      ?? candidates[0];
     if (!check) {
-      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is missing: ${id}`, [id]));
+      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is missing: ${value}`, [value]));
       continue;
     }
     if (check.status !== "passed") {
-      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is not passed: ${id}`, [id]));
+      errors.push(checkError("E_EVIDENCE_REQUIRED", `Required check is not passed: ${value}`, [value]));
       continue;
     }
     if (!allowInferred && check.evidenceKind !== "OBSERVED") {
-      errors.push(checkError("E_EVIDENCE_KIND_INVALID", `Required check must be observed: ${id}`, [id]));
+      errors.push(checkError("E_EVIDENCE_KIND_INVALID", `Required check must be observed: ${value}`, [value]));
     }
   }
   return errors;
 }
+
+export function requiredChecksSatisfied(checks, requiredIds, options = {}) {
+  return requiredChecksSatisfiedBy(checks, requiredIds, (check) => check.id, options);
+}
+
+export function requiredChecksSatisfiedForRequirements(checks, requiredRequirements, options = {}) {
+  return requiredChecksSatisfiedBy(checks, requiredRequirements, (check) => check.requirement, options);
+}

package/src/core/completion-relationships.js

@@ -1,5 +1,5 @@
 import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
-import { assertCheckList, requiredChecksSatisfied } from "./checks.js";
+import { assertCheckList, requiredChecksSatisfiedForRequirements } from "./checks.js";
 import { assertCoverageList, coverageForRequirements } from "./coverage.js";
 import { assertEvidenceList } from "./evidence.js";
 
@@ -86,7 +86,7 @@ export function completionRelationshipErrors({
     addAssertion(errors, () => assertCheckList(receipt.checks, "receipt.checks"), "E_CHECK_INVALID", [ARTIFACT_PATHS.receipt]);
     addAssertion(errors, () => assertEvidenceList(receipt.evidence ?? [], "receipt.evidence"), "E_EVIDENCE_INVALID", [ARTIFACT_PATHS.receipt]);
     if (requireRequiredChecks) {
-      for (const error of requiredChecksSatisfied(receipt.checks, requiredEvidence)) {
+      for (const error of requiredChecksSatisfiedForRequirements(receipt.checks, requiredEvidence)) {
         errors.push(issue(error.code, error.message, [ARTIFACT_PATHS.receipt]));
       }
     }

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;
 }