@cassiomc1/forgeloop 0.1.6 → 0.1.9

package/src/commands/update.js

@@ -1,25 +1,307 @@
+import { rmdir, unlink } from "node:fs/promises";
+
 import { assertSafePath, fileExists, ensureWithin, readBytes, writeFileAtomic } from "../core/filesystem.js";
 import {
+  createManifest,
   PACKAGE_NAME,
   readManifest,
   sha256,
   writeManifest,
 } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
+import { isNativeAdapterPath, LAYOUT_VERSION } from "../core/target-layout.js";
 
 const PROFILE_PATH = "PROJECT_PROFILE.md";
+const LEGACY_CLEANUP_DIRECTORIES = Object.freeze(["ENG", "schemas"]);
+
+function migrationConflict(code, path, message) {
+  return { code, path, message };
+}
+
+function addAction(actions, dryRun, action, path, details = {}) {
+  actions.push({ action: dryRun ? `would-${action}` : action, path, ...details });
+}
+
+async function verifyWrite(filePath, expectedBytes) {
+  const actualBytes = await readBytes(filePath);
+  if (!actualBytes.equals(expectedBytes)) {
+    const error = new Error(`Migration write verification failed for ${filePath}`);
+    error.code = "E_MIGRATION_WRITE_VERIFY";
+    throw error;
+  }
+}
+
+async function removeEmptyLegacyDirectory(target, relativePath, dryRun) {
+  await assertSafePath(target, relativePath);
+  if (dryRun) return;
+  try {
+    await rmdir(ensureWithin(target, relativePath));
+  } catch (error) {
+    if (!["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code)) throw error;
+  }
+}
+
+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);
+    }
+  }
+}
+
+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 = [];
+  const writes = [];
+  const cleanupFiles = new Set();
+  const cleanupDirectories = new Set();
+
+  // Validate every path before creating the migration plan or touching data.
+  for (const entry of entries) {
+    await assertSafePath(target, entry.relativePath);
+    if (entry.legacyRelativePath !== entry.relativePath) {
+      await assertSafePath(target, entry.legacyRelativePath);
+    }
+  }
+
+  for (const entry of entries) {
+    const destination = ensureWithin(target, entry.relativePath);
+    const legacyDestination = ensureWithin(target, entry.legacyRelativePath);
+    const sourceHash = sha256(entry.bytes);
+    const destinationExists = await fileExists(destination);
+    const legacyExists = entry.legacyRelativePath !== entry.relativePath
+      && await fileExists(legacyDestination);
+    const legacyRecord = currentManifest.files[entry.legacyRelativePath];
+    const destinationRecord = currentManifest.files[entry.relativePath];
+
+    if (isNativeAdapterPath(entry.relativePath)) {
+      if (!destinationExists) {
+        addAction(actions, dryRun, "create", entry.relativePath);
+        writes.push({ destination, bytes: entry.bytes });
+        nextManifest.files[entry.relativePath] = { sha256: sourceHash, preserve: false };
+        continue;
+      }
+
+      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" });
+        } else {
+          addAction(actions, dryRun, "update-adapter", entry.relativePath);
+          writes.push({ destination, bytes: entry.bytes });
+        }
+        nextManifest.files[entry.relativePath] = { sha256: sourceHash, preserve: false };
+        continue;
+      }
+
+      conflicts.push(migrationConflict(
+        "E_NATIVE_ADAPTER_MIGRATION_CONFLICT",
+        entry.relativePath,
+        legacyRecord
+          ? "Managed native adapter was modified; it was preserved and was not silently overwritten."
+          : "Native adapter is not owned by the legacy manifest; it was preserved and was not silently adopted.",
+      ));
+      addAction(actions, dryRun, "preserve-conflict", entry.relativePath, {
+        reason: legacyRecord ? "managed-modified" : "unmanaged",
+      });
+      if (legacyRecord) nextManifest.files[entry.relativePath] = { ...legacyRecord };
+      continue;
+    }
+
+    if (destinationExists) {
+      const currentBytes = await readBytes(destination);
+      const currentHash = sha256(currentBytes);
+      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] = 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] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
+      continue;
+    }
 
-export async function runUpdate({ target, dryRun, packageRoot, packageVersion }) {
+    const legacyBytes = await readBytes(legacyDestination);
+    const legacyHash = sha256(legacyBytes);
+    const unchangedManaged = Boolean(legacyRecord) && legacyHash === legacyRecord.sha256;
+
+    if (entry.sourcePath === PROFILE_PATH && legacyRecord) {
+      addAction(actions, dryRun, "move-profile", entry.legacyRelativePath, { to: entry.relativePath });
+      writes.push({ destination, bytes: legacyBytes });
+      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 });
+      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 });
+      addLegacyCleanup(cleanupFiles, cleanupDirectories, entry.legacyRelativePath);
+      nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, false, legacyHash);
+      continue;
+    }
+
+    const conflict = entry.sourcePath === PROFILE_PATH
+      ? migrationConflict(
+        "E_PROFILE_MIGRATION_CONFLICT",
+        entry.legacyRelativePath,
+        "Project profile is not owned by the legacy manifest; it was preserved and was not overwritten or deleted.",
+      )
+      : migrationConflict(
+        "E_LEGACY_FILE_MIGRATION_CONFLICT",
+        entry.legacyRelativePath,
+        legacyRecord
+          ? "Managed legacy file was modified; it was preserved while the hidden canonical file was installed."
+          : "Unmanaged legacy file was preserved while the hidden canonical file was installed.",
+      );
+    conflicts.push(conflict);
+    addAction(actions, dryRun, "preserve-conflict", entry.legacyRelativePath, {
+      to: entry.relativePath,
+      reason: legacyRecord ? "managed-modified" : "unmanaged",
+    });
+    writes.push({ destination, bytes: entry.bytes });
+    nextManifest.files[entry.relativePath] = manifestRecord(sourceHash, entry.sourcePath === PROFILE_PATH);
+  }
+
+  // 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 });
+
+  // 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, hooks = {} }) {
   const currentManifest = await readManifest(target);
   if (!currentManifest) {
     throw new Error("No .forgeloop/manifest.json found; run forgeloop init first.");
   }
 
   const entries = await readTemplateEntries(packageRoot);
+  if ((currentManifest.layoutVersion ?? 1) < LAYOUT_VERSION) {
+    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));
 
@@ -36,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",
@@ -47,7 +353,8 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
         entry,
         record: {
           sha256: sourceHash,
-          preserve: entry.relativePath === PROFILE_PATH,
+          preserve: entry.sourcePath === PROFILE_PATH,
+          ...(record?.legacySha256 ? { legacySha256: record.legacySha256 } : {}),
         },
       });
       continue;
@@ -58,7 +365,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion })
       continue;
     }
 
-    if (record.preserve || entry.relativePath === PROFILE_PATH) {
+    if (record.preserve || entry.sourcePath === PROFILE_PATH) {
       actions.push({ action: "skip", path: entry.relativePath, reason: "preserved" });
       continue;
     }
@@ -105,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/commands/validate-protocol.js

@@ -6,6 +6,8 @@ import { assertRouteInvariants } from "../core/router.js";
 import { assertWorkStateSemantics, classifyLoadedWorkState } from "../core/work-state.js";
 import { validateReceipt } from "../core/receipt.js";
 import { validateTaskBrief, validateDelegatedResult } from "../core/delegation.js";
+import { ARTIFACT_PATHS, readJsonArtifact } from "../core/artifacts.js";
+import { evaluatePreflight, validateReadyProtocolConsistency } from "../core/preflight.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
@@ -102,11 +104,26 @@ export async function runValidateProtocol({
     taskBriefs,
     delegatedResults,
   });
-  if (readErrors.length > 0 || schemaErrors.length > 0) {
+  let readyConsistencyErrors = [];
+  try {
+    const persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+    if (persistedPreflight.value.status === "READY") {
+      readyConsistencyErrors = await validateReadyProtocolConsistency({
+        target,
+        packageRoot,
+        persisted: persistedPreflight.value,
+        current: await evaluatePreflight({ target, packageRoot }),
+      });
+    }
+  } catch {
+    // A missing or invalid preflight is already outside the optional protocol set.
+  }
+  if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0) {
     return {
       ...result,
       status: "INVALID",
-      errors: [...result.errors, ...readErrors, ...schemaErrors].sort((left, right) => left.code.localeCompare(right.code) || left.message.localeCompare(right.message)),
+      errors: [...result.errors, ...readErrors, ...schemaErrors, ...readyConsistencyErrors]
+        .sort((left, right) => left.code.localeCompare(right.code) || left.message.localeCompare(right.message)),
     };
   }
   return result;

package/src/core/audit.js

@@ -4,6 +4,7 @@ import { readManifest } from "./manifest.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { readJsonArtifact } from "./artifacts.js";
 import { currentChangedPaths } from "./repository.js";
+import { validateReadyProtocolConsistency } from "./preflight.js";
 
 function sortErrors(errors) {
   return [...errors].sort((left, right) => left.code.localeCompare(right.code)
@@ -42,7 +43,21 @@ export async function evaluateAudit({ target, packageRoot, strict = false } = {}
   } catch (error) {
     manifestError = error.message;
   }
-  const errors = sortErrors(completion.errors);
+  let readyConsistencyErrors = [];
+  try {
+    const persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+    if (persistedPreflight.value.status === "READY") {
+      readyConsistencyErrors = await validateReadyProtocolConsistency({
+        target,
+        packageRoot,
+        persisted: persistedPreflight.value,
+        current: completion.preflight,
+      });
+    }
+  } catch {
+    // Completion already reports missing or invalid preflight artifacts.
+  }
+  const errors = sortErrors([...completion.errors, ...readyConsistencyErrors]);
   const changedPaths = await compareChangedPaths(target, packageRoot);
   if (changedPaths.status === "MISMATCH") {
     errors.push({

package/src/core/events.js

@@ -19,6 +19,14 @@ export const LIFECYCLE_MILESTONES = Object.freeze([
   "VERIFICATION_RECORDED",
   "COMPLETION_VALIDATED",
 ]);
+export const ACTIVATION_EVENT_MATRIX = Object.freeze([
+  Object.freeze({ stage: "task received", event: "TASK_RECEIVED", requiredFor: "new activation" }),
+  Object.freeze({ stage: "contract validated", event: "CONTRACT_VALIDATED", requiredFor: "preflight readiness" }),
+  Object.freeze({ stage: "route validated", event: "ROUTE_VALIDATED", requiredFor: "preflight readiness" }),
+  Object.freeze({ stage: "gate satisfied", event: "GATE_SATISFIED", requiredFor: "each satisfied gate" }),
+  Object.freeze({ stage: "preflight blocked", event: "PREFLIGHT_BLOCKED", requiredFor: "blocked activation" }),
+  Object.freeze({ stage: "preflight ready", event: "PREFLIGHT_READY", requiredFor: "resumable readiness" }),
+]);
 const REPEATABLE_MILESTONES = new Set(["VERIFICATION_RECORDED"]);
 
 function eventHash(event) {

package/src/core/guide-metadata.js

@@ -3,6 +3,7 @@ import path from "node:path";
 
 const GUIDE_FILES = Object.freeze({
   premium: "ENG/premium-sites-studio-eng.md",
+  taste: "ENG/taste-frontend-eng.md",
   clean: "ENG/clean-code-eng.md",
   test: "ENG/test-code-eng.md",
   security: "ENG/sec-code-eng.md",

package/src/core/inspect.js

@@ -6,8 +6,9 @@ import { inspectSchemaHealth } from "./schema-validation.js";
 import { readAndClassifyWorkState, WORK_STATE_PATH } from "./work-state.js";
 import { createEvidence } from "./evidence.js";
 import { runDoctor } from "../commands/doctor.js";
+import { findProfilePath } from "./profile.js";
+import { FORGELOOP_KIT_DIR } from "./target-layout.js";
 
-const PROFILE_PATH = "PROJECT_PROFILE.md";
 function profileMetadata(bytes) {
   const text = bytes.toString("utf8");
   return {
@@ -25,14 +26,21 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     manifestError = error.message;
   }
 
-  const profilePath = ensureWithin(target, PROFILE_PATH);
-  const profile = (await fileExists(profilePath))
-    ? profileMetadata(await readBytes(profilePath))
+  const profileRelativePath = await findProfilePath(target);
+  const profilePath = profileRelativePath ? ensureWithin(target, profileRelativePath) : null;
+  const profile = (profilePath && await fileExists(profilePath))
+    ? { ...profileMetadata(await readBytes(profilePath)), path: profileRelativePath }
     : { mode: null, status: null };
   const statePath = ensureWithin(target, WORK_STATE_PATH);
   const statePresent = await fileExists(statePath);
   const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
-  const schemaHealth = await inspectSchemaHealth(target);
+  const schemaRoot = manifest?.layoutVersion >= 2
+    ? ensureWithin(target, FORGELOOP_KIT_DIR)
+    : target;
+  const schemaHealth = await inspectSchemaHealth(schemaRoot);
+  const schemaPathPrefix = manifest?.layoutVersion >= 2
+    ? `${FORGELOOP_KIT_DIR}/schemas`
+    : "schemas";
   const doctor = await runDoctor({ target, packageRoot });
   const agents = await Promise.all(AGENT_SUPPORT.map(async (record) => ({
     id: record.id,
@@ -50,12 +58,12 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
       findings.push({
         code: `schema-${schema.status}`,
         severity: "error",
-        path: `schemas/${schema.name}.schema.json`,
+        path: `${schemaPathPrefix}/${schema.name}.schema.json`,
         message: schema.error ?? `Schema is ${schema.status}.`,
         remediation: "Restore the shipped schema and rerun inspect.",
         evidence: createEvidence({
           kind: schema.status === "missing" ? "NOT_VERIFIED" : "OBSERVED",
-          source: `schemas/${schema.name}.schema.json`,
+          source: `${schemaPathPrefix}/${schema.name}.schema.json`,
           result: schema.status,
         }),
       });
@@ -88,6 +96,7 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
       present: manifest !== null,
       status: manifestError ? "invalid" : manifest ? "ready" : "missing",
       packageVersion: manifest?.packageVersion ?? null,
+      layoutVersion: manifest?.layoutVersion ?? 1,
       error: manifestError,
     },
     profile,

package/src/core/manifest.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 
 import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
 import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import { LAYOUT_VERSION, LEGACY_LAYOUT_VERSION } from "./target-layout.js";
 
 export const MANIFEST_SCHEMA_VERSION = 1;
 export const MANIFEST_PATH = ".forgeloop/manifest.json";
@@ -15,6 +16,7 @@ export function sha256(bytes) {
 export function createManifest(packageVersion) {
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
+    layoutVersion: LAYOUT_VERSION,
     packageName: PACKAGE_NAME,
     packageVersion,
     files: {},
@@ -28,6 +30,10 @@ function validateManifest(manifest) {
   if (manifest.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
     throw new Error(`Unsupported manifest schema: ${manifest.schemaVersion}`);
   }
+  if (manifest.layoutVersion !== undefined
+    && ![LEGACY_LAYOUT_VERSION, LAYOUT_VERSION].includes(manifest.layoutVersion)) {
+    throw new Error(`Unsupported manifest layout: ${manifest.layoutVersion}`);
+  }
   if (typeof manifest.packageVersion !== "string" || !manifest.packageVersion) {
     throw new Error("Manifest packageVersion is required");
   }
@@ -43,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;
 }

package/src/core/native-adapters.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { isKitPath } from "./target-layout.js";
+
+const LEGACY_REFERENCE_PATTERN = /(?:\.\.\/|\.\/)+(?:LOOP_ENGINEERING|PROJECT_PROFILE|GUIDE_ROUTER)\.md\b/g;
+
+export function nativeShimPrefix(relativePath) {
+  if (relativePath.startsWith(".cursor/")) return "../../.forgeloop/kit";
+  if (relativePath.startsWith(".github/")) return "../.forgeloop/kit";
+  return ".forgeloop/kit";
+}
+
+export function nativeShimReferences(relativePath) {
+  const prefix = nativeShimPrefix(relativePath);
+  return [
+    `${prefix}/LOOP_ENGINEERING.md`,
+    `${prefix}/AGENT_COMPATIBILITY.md`,
+  ];
+}
+
+export function nativeShim(relativePath) {
+  const kitPrefix = nativeShimPrefix(relativePath);
+  return `# ForgeLoop native adapter\n\nRead and follow the canonical ForgeLoop protocol in ${kitPrefix}/LOOP_ENGINEERING.md and ${kitPrefix}/AGENT_COMPATIBILITY.md.\nThe canonical guides and schemas are under ${kitPrefix}/; keep this adapter concise and preserve any host-specific instructions.\n`;
+}
+
+export function resolveNativeReference(relativePath, reference) {
+  return path.posix.normalize(path.posix.join(path.posix.dirname(relativePath), reference));
+}
+
+export function inspectNativeAdapter(relativePath, bytes) {
+  const text = Buffer.from(bytes).toString("utf8");
+  const expected = nativeShimReferences(relativePath);
+  const legacyReferences = text.match(LEGACY_REFERENCE_PATTERN) ?? [];
+  const missingReferences = expected.filter((reference) => !text.includes(reference));
+  const resolvedReferences = expected.map((reference) => ({
+    reference,
+    path: resolveNativeReference(relativePath, reference),
+  }));
+
+  return {
+    text,
+    expected,
+    legacyReferences,
+    missingReferences,
+    resolvedReferences,
+    hasForgeLoopMarker: /forgeloop/i.test(text),
+  };
+}
+
+export async function validateNativeAdapterTargets({ target, relativePath, bytes }) {
+  const inspection = inspectNativeAdapter(relativePath, bytes);
+  const invalidReferences = inspection.resolvedReferences.filter(({ path: resolvedPath }) => !isKitPath(resolvedPath));
+  const missingTargets = [];
+
+  for (const { path: resolvedPath } of inspection.resolvedReferences) {
+    if (!isKitPath(resolvedPath)) continue;
+    try {
+      await assertSafePath(target, resolvedPath);
+      if (!(await fileExists(ensureWithin(target, resolvedPath)))) missingTargets.push(resolvedPath);
+    } catch (error) {
+      invalidReferences.push({ path: resolvedPath, error: error.message });
+    }
+  }
+
+  return {
+    ...inspection,
+    invalidReferences,
+    missingTargets,
+    stale: inspection.legacyReferences.length > 0
+      || inspection.missingReferences.length > 0
+      || invalidReferences.length > 0,
+  };
+}