@cassiomc1/forgeloop 0.1.6 → 0.1.8

package/src/core/preflight.js

@@ -5,13 +5,15 @@ import { requiredGatesForGuides } from "./guide-metadata.js";
 import { assertRouteInvariants } from "./router.js";
 import { assertSourceProvenance } from "./sources.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { readWorkState } from "./work-state.js";
 import { readConfig } from "./config.js";
 import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
 import { sha256 } from "./manifest.js";
-import { validateProfileSources } from "./profile.js";
+import { findProfilePath, validateProfileSources } from "./profile.js";
 import { assertStateIdentity } from "./completion-relationships.js";
+import { ensureResumableState, synchronizePreflightState } from "./resumability.js";
+import { PROFILE_PATH } from "./target-layout.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
@@ -91,10 +93,9 @@ export function validatePersistedPreflight(persisted, current) {
 }
 
 async function readProfile(target) {
-  const relativePath = "PROJECT_PROFILE.md";
-  await assertSafePath(target, relativePath);
+  const relativePath = await findProfilePath(target);
+  if (!relativePath) return { status: "missing", fingerprint: null };
   const filePath = ensureWithin(target, relativePath);
-  if (!(await fileExists(filePath))) return { status: "missing", fingerprint: null };
   const bytes = await readBytes(filePath);
   const text = bytes.toString("utf8");
   const mode = text.match(/^profile-mode:\s*([^\s]+)\s*$/m)?.[1] ?? null;
@@ -204,7 +205,7 @@ export async function evaluatePreflight({ target, packageRoot, strict = false }
   const config = await optionalConfig(target, packageRoot, errors);
   const effectiveStrict = strict || config.complianceMode === "strict";
   if (effectiveStrict && profile.status !== "verified") {
-    errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", ["PROJECT_PROFILE.md"]));
+    errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", [PROFILE_PATH]));
   }
   const unresolvedDecisions = contract?.value?.unresolvedDecisions ?? [];
   if (unresolvedDecisions.length > 0) {
@@ -348,62 +349,235 @@ function sameReadyPreflightEvent(event, result) {
     && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates);
 }
 
-function planReadyPreflightLifecycleWrite(ledger, result) {
-  if (!ledger) return { appendEvents: false };
-  const existing = ledger.events.find((event) => event.event === "PREFLIGHT_READY");
-  if (existing) {
-    if (sameReadyPreflightEvent(existing, result)) return { appendEvents: false };
+export async function validateReadyProtocolConsistency({
+  target,
+  packageRoot,
+  persisted,
+  current = null,
+} = {}) {
+  if (persisted?.status !== "READY") return [];
+  const result = current ?? await evaluatePreflight({ target, packageRoot });
+  const errors = [...validatePersistedPreflight(persisted, result)];
+
+  let state = null;
+  try {
+    state = await readWorkState(target, packageRoot);
+  } catch (error) {
+    errors.push(issue("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]));
+  }
+  if (!state) {
+    errors.push(issue(
+      "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
+      "A persisted READY preflight must have a resumable work-state checkpoint",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.state],
+    ));
+  } else {
+    if (state.taskId !== persisted.taskId) {
+      errors.push(issue(
+        "E_STATE_TASK_MISMATCH",
+        "The resumable checkpoint does not belong to the READY preflight task",
+        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight],
+      ));
+    }
+    if (state.contractFingerprint !== result.fingerprints.contract) {
+      errors.push(issue(
+        "E_CONTRACT_STALE",
+        "The resumable checkpoint does not match the READY contract fingerprint",
+        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.contract],
+      ));
+    }
+    if (state.routeFingerprint !== result.fingerprints.routing) {
+      errors.push(issue(
+        "E_ROUTE_STALE",
+        "The resumable checkpoint does not match the READY routing fingerprint",
+        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route],
+      ));
+    }
+    if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
+      errors.push(issue(
+        "E_ROUTE_GUIDE_MISMATCH",
+        "The resumable checkpoint guides do not match the READY routing result",
+        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.route],
+      ));
+    }
+    if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
+      || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
+      errors.push(issue(
+        "E_PREFLIGHT_GATES_STALE",
+        "The resumable checkpoint gate sets do not match the READY preflight",
+        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.gates],
+      ));
+    }
+  }
+
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    errors.push(...ledger.errors.map((error) => issue(
+      error.code ?? "E_EVENT_INVALID",
+      error.message,
+      [ARTIFACT_PATHS.events],
+    )));
+  }
+  const events = ledger.events ?? [];
+  for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"]) {
+    if (!events.some((event) => event.event === requiredEvent && event.taskId === persisted.taskId)) {
+      errors.push(issue(
+        "E_PREFLIGHT_EVENT_MISSING",
+        `READY preflight is missing lifecycle event: ${requiredEvent}`,
+        [ARTIFACT_PATHS.events, ARTIFACT_PATHS.preflight],
+      ));
+    }
+  }
+  for (const gate of persisted.satisfiedGates ?? []) {
+    if (!events.some((event) => event.event === "GATE_SATISFIED"
+      && event.taskId === persisted.taskId
+      && event.details?.gate === gate)) {
+      errors.push(issue(
+        "E_PREFLIGHT_GATE_EVENT_MISSING",
+        `READY preflight is missing lifecycle gate event: ${gate}`,
+        [ARTIFACT_PATHS.events, `${ARTIFACT_PATHS.gates}/${gate}.json`],
+      ));
+    }
+  }
+  const readyEvents = events.filter((event) => event.event === "PREFLIGHT_READY" && event.taskId === persisted.taskId);
+  if (readyEvents.length === 0) {
+    errors.push(issue(
+      "E_PREFLIGHT_READY_EVENT_MISSING",
+      "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events],
+    ));
+  } else if (!readyEvents.some((event) => sameReadyPreflightEvent(event, result))) {
+    errors.push(issue(
+      "E_PREFLIGHT_READY_EVENT_MISMATCH",
+      "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight",
+      [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events],
+    ));
+  }
+  return sortIssues(errors);
+}
+
+function sameBlockedPreflightEvent(event, result) {
+  return event.event === "PREFLIGHT_BLOCKED"
+    && event.taskId === result.taskId
+    && event.fingerprint === (result.fingerprints.contract ?? undefined)
+    && sameStringSet(event.details?.requiredGates, result.requiredGates)
+    && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates)
+    && event.details?.routingFingerprint === result.fingerprints.routing;
+}
+
+function assertExistingReadyLifecycleCompatibility(ledger, result) {
+  if (result.status !== "READY") return;
+  const existingReady = ledger?.events?.find((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
+  if (existingReady && !sameReadyPreflightEvent(existingReady, result)) {
     throw preflightError(
       "E_PHASE_CHRONOLOGY_INVALID",
       "PREFLIGHT_READY already exists with different READY preflight details; repair the contract, route, or gate lifecycle before refreshing preflight",
       [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route, ARTIFACT_PATHS.gates],
     );
   }
-  const lastMilestone = ledger.events.reduce(
-    (last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)),
-    -1,
-  );
-  const routeMilestone = LIFECYCLE_MILESTONES.indexOf("ROUTE_VALIDATED");
-  const preflightMilestone = LIFECYCLE_MILESTONES.indexOf("PREFLIGHT_READY");
-  if (lastMilestone < routeMilestone) return { appendEvents: false };
-  if (lastMilestone !== preflightMilestone - 1) {
-    throw preflightError(
-      "E_PHASE_CHRONOLOGY_INVALID",
-      "PREFLIGHT_READY cannot be appended after the current lifecycle ledger",
-      [ARTIFACT_PATHS.events],
-    );
-  }
-  return { appendEvents: true };
 }
 
-export async function runPreflight({ target, packageRoot, strict = false, persist = true } = {}) {
-  const result = await evaluatePreflight({ target, packageRoot, strict });
-  if (persist) {
-    const ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
-    assertPreflightResultPersistenceSafety(result);
-    const lifecycleWrite = result.status === "READY"
-      ? planReadyPreflightLifecycleWrite(ledger, result)
-      : { appendEvents: true };
-    await writeJsonArtifact(target, ARTIFACT_PATHS.preflight, result, "preflight", packageRoot);
-    if (result.taskId !== "unknown" && lifecycleWrite.appendEvents) {
-      for (const gate of result.satisfiedGates) {
-        await appendProtocolEvent(target, {
-          taskId: result.taskId,
-          event: "GATE_SATISFIED",
-          details: { gate },
-        }, packageRoot);
-      }
-      await appendProtocolEvent(target, {
+async function appendActivationEvents(target, packageRoot, ledger, result) {
+  const events = [...(ledger?.events ?? [])];
+  const hasEvent = (eventName) => events.some((event) => event.event === eventName && event.taskId === result.taskId);
+  const append = async (input) => {
+    const event = await appendProtocolEvent(target, input, packageRoot);
+    events.push(event);
+  };
+
+  if (events.length === 0) {
+    await append({ taskId: result.taskId, event: "TASK_RECEIVED" });
+  }
+  if (result.contract.status === "valid" && !hasEvent("CONTRACT_VALIDATED")) {
+    await append({ taskId: result.taskId, event: "CONTRACT_VALIDATED", fingerprint: result.fingerprints.contract });
+  }
+  if (result.routing.status === "valid" && !hasEvent("ROUTE_VALIDATED")) {
+    await append({ taskId: result.taskId, event: "ROUTE_VALIDATED", fingerprint: result.fingerprints.routing });
+  }
+  for (const gate of result.satisfiedGates) {
+    if (!events.some((event) => event.event === "GATE_SATISFIED"
+      && event.taskId === result.taskId
+      && event.details?.gate === gate)) {
+      await append({ taskId: result.taskId, event: "GATE_SATISFIED", details: { gate } });
+    }
+  }
+
+  const existingReady = events.find((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
+  if (result.status === "READY") {
+    if (existingReady && !sameReadyPreflightEvent(existingReady, result)) {
+      throw preflightError(
+        "E_PHASE_CHRONOLOGY_INVALID",
+        "PREFLIGHT_READY already exists with different READY preflight details; repair the contract, route, or gate lifecycle before refreshing preflight",
+        [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract, ARTIFACT_PATHS.route, ARTIFACT_PATHS.gates],
+      );
+    }
+    if (!existingReady) {
+      await append({
         taskId: result.taskId,
-        event: result.status === "READY" ? "PREFLIGHT_READY" : "PREFLIGHT_BLOCKED",
+        event: "PREFLIGHT_READY",
         fingerprint: result.fingerprints.contract ?? undefined,
         details: {
           requiredGates: result.requiredGates,
           satisfiedGates: result.satisfiedGates,
           routingFingerprint: result.fingerprints.routing,
         },
-      }, packageRoot);
+      });
+    }
+  } else if (!events.some((event) => sameBlockedPreflightEvent(event, result))) {
+    await append({
+      taskId: result.taskId,
+      event: "PREFLIGHT_BLOCKED",
+      fingerprint: result.fingerprints.contract ?? undefined,
+      details: {
+        requiredGates: result.requiredGates,
+        satisfiedGates: result.satisfiedGates,
+        routingFingerprint: result.fingerprints.routing,
+      },
+    });
+  }
+  return events;
+}
+
+export async function runPreflight({ target, packageRoot, strict = false, persist = true } = {}) {
+  let result = await evaluatePreflight({ target, packageRoot, strict });
+  if (!persist) return result;
+
+  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
+  assertPreflightResultPersistenceSafety(result);
+  assertExistingReadyLifecycleCompatibility(ledger, result);
+
+  let contract = null;
+  let route = null;
+  if (result.contract.status === "valid" && result.routing.status === "valid") {
+    contract = await readContract(target, packageRoot);
+    route = await readPersistedRoute(target, packageRoot);
+    const state = await ensureResumableState({ target, packageRoot, contract, route });
+    if (state) {
+      await synchronizePreflightState({
+        target,
+        packageRoot,
+        state,
+        contract,
+        route,
+        requiredGates: result.requiredGates,
+        satisfiedGates: result.satisfiedGates,
+        complianceMode: result.policy?.complianceMode,
+      });
+      result = await evaluatePreflight({ target, packageRoot, strict });
+      assertPreflightResultPersistenceSafety(result);
+      assertExistingReadyLifecycleCompatibility(ledger, result);
+      ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
+    }
+  }
+
+  if (result.taskId !== "unknown") {
+    await appendActivationEvents(target, packageRoot, ledger, result);
+    const afterEvents = await validateEventLedger(target, packageRoot);
+    if (!afterEvents.valid) {
+      const first = afterEvents.errors[0];
+      throw preflightError(first.code, first.message, [ARTIFACT_PATHS.events]);
     }
   }
+  await writeJsonArtifact(target, ARTIFACT_PATHS.preflight, result, "preflight", packageRoot);
   return result;
 }

package/src/core/profile.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { assertSourceProvenance } from "./sources.js";
+import { LEGACY_PROFILE_PATH, PROFILE_PATH } from "./target-layout.js";
 
 const SOURCE_ID_PATTERN = /\b(?:USER|FILE|CMD|DECISION|OBS|INFER|UNKNOWN)-[A-Z0-9_-]+\b/g;
 const DIRECTIVE_PATTERN = /forgeloop-source:\s*([A-Z0-9_-]+)\s+kind=([a-z-]+)/gi;
@@ -12,12 +13,11 @@ function issue(code, message, artifacts = []) {
 }
 
 export async function validateProfileSources(target, packageRoot) {
-  const profilePath = "PROJECT_PROFILE.md";
-  await assertSafePath(target, profilePath);
-  const absolutePath = ensureWithin(target, profilePath);
-  if (!(await fileExists(absolutePath))) {
+  const profilePath = await findProfilePath(target);
+  if (!profilePath) {
     return { status: "missing", refs: [], errors: [] };
   }
+  const absolutePath = ensureWithin(target, profilePath);
   const text = await readFile(absolutePath, "utf8");
   const refs = [...new Set(text.match(SOURCE_ID_PATTERN) ?? [])].sort();
   const directives = [...text.matchAll(DIRECTIVE_PATTERN)].map((match) => ({ id: match[1], kind: match[2] }));
@@ -46,3 +46,11 @@ export async function validateProfileSources(target, packageRoot) {
   }
   return { status: errors.length === 0 ? "valid" : "invalid", refs, errors };
 }
+
+export async function findProfilePath(target) {
+  for (const relativePath of [PROFILE_PATH, LEGACY_PROFILE_PATH]) {
+    await assertSafePath(target, relativePath);
+    if (await fileExists(ensureWithin(target, relativePath))) return relativePath;
+  }
+  return null;
+}

package/src/core/protocol.js

@@ -13,6 +13,7 @@ export const FAILURE_CLASSES = Object.freeze([
   "ENVIRONMENT_FAILURE",
   "EXTERNAL_SERVICE_FAILURE",
   "STALE_STATE_FAILURE",
+  "OPERATOR_INTERRUPTION",
 ]);
 
 export const FAILURE_CODES = Object.freeze([
@@ -47,6 +48,12 @@ export const FAILURE_CODES = Object.freeze([
   "E_COMPLETION_REJECTED",
   "E_PUBLICATION_CLAIM_UNVERIFIED",
   "E_PRODUCTION_READINESS_UNVERIFIED",
+  "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
+  "E_PREFLIGHT_READY_EVENT_MISSING",
+  "E_PREFLIGHT_READY_EVENT_MISMATCH",
+  "E_PREFLIGHT_EVENT_MISSING",
+  "E_PREFLIGHT_GATE_EVENT_MISSING",
+  "E_PREFLIGHT_GATES_STALE",
 ]);
 
 export const WORK_PHASES = Object.freeze([
@@ -74,6 +81,7 @@ export const GUIDE_IDS = Object.freeze([
   "performance",
   "accessibility",
   "games",
+  "taste",
 ]);
 
 export const GUIDE_ORDER = GUIDE_IDS;

package/src/core/report.js

@@ -2,9 +2,12 @@ import { readFile } from "node:fs/promises";
 
 import { evaluateAudit } from "./audit.js";
 import { fileExists, ensureWithin } from "./filesystem.js";
+import { findProfilePath } from "./profile.js";
 
 async function profileStatus(target) {
-  const profilePath = ensureWithin(target, "PROJECT_PROFILE.md");
+  const relativePath = await findProfilePath(target);
+  if (!relativePath) return "NOT_VERIFIED";
+  const profilePath = ensureWithin(target, relativePath);
   if (!(await fileExists(profilePath))) return "NOT_VERIFIED";
   const text = await readFile(profilePath, "utf8");
   return /^profile-status:\s*verified\s*$/m.test(text) ? "PASS" : "NOT_VERIFIED";

package/src/core/resumability.js

@@ -0,0 +1,61 @@
+import { currentRepositoryFingerprint } from "./repository.js";
+import { createWorkState, readWorkState, writeWorkState } from "./work-state.js";
+
+const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
+
+export async function ensureResumableState({ target, packageRoot, contract, route }) {
+  if (!contract || !route) return null;
+  const existing = await readWorkState(target, packageRoot);
+  if (existing) return existing;
+
+  const state = createWorkState({
+    taskId: contract.value.taskId,
+    contractFingerprint: contract.fingerprint,
+    routeFingerprint: route.fingerprint,
+    repositoryFingerprint: await currentRepositoryFingerprint(target),
+    phase: "ROUTED",
+    selectedGuides: route.value.guides,
+    completedSteps: ["contract", "route"],
+    pendingSteps: DEFAULT_PENDING_STEPS,
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+  });
+  await writeWorkState(target, state, { packageRoot });
+  return state;
+}
+
+export async function synchronizePreflightState({
+  target,
+  packageRoot,
+  state,
+  contract,
+  route,
+  requiredGates,
+  satisfiedGates,
+  complianceMode,
+}) {
+  const candidate = createWorkState({
+    ...state,
+    taskId: contract.value.taskId,
+    contractFingerprint: contract.fingerprint,
+    routeFingerprint: route.fingerprint,
+    selectedGuides: route.value.guides,
+    requiredGates: [...requiredGates],
+    satisfiedGates: [...satisfiedGates],
+    ...(complianceMode ? { complianceMode } : {}),
+    lastUpdated: state.lastUpdated,
+  });
+  const withoutTimestamp = (value) => {
+    const copy = structuredClone(value);
+    delete copy.lastUpdated;
+    return copy;
+  };
+  if (JSON.stringify(withoutTimestamp(candidate)) === JSON.stringify(withoutTimestamp(state))) {
+    return state;
+  }
+  const next = { ...candidate, lastUpdated: new Date().toISOString() };
+  await writeWorkState(target, next, { packageRoot });
+  return next;
+}

package/src/core/route-artifact.js

@@ -1,13 +1,16 @@
 import { assertRouteInvariants } from "./router.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
+import { ensureResumableState } from "./resumability.js";
 
 export async function persistRoute(target, route, packageRoot, options = {}) {
   assertRouteInvariants(route);
   let { contractFingerprint, ...writeOptions } = options;
+  let contractArtifact = null;
   if (contractFingerprint === undefined) {
     try {
-      contractFingerprint = (await readContract(target, packageRoot)).fingerprint;
+      contractArtifact = await readContract(target, packageRoot);
+      contractFingerprint = contractArtifact.fingerprint;
     } catch (error) {
       if (error.code !== "ARTIFACT_MISSING") throw error;
     }
@@ -16,7 +19,7 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     ? route
     : { ...route, contractFingerprint };
   assertRouteInvariants(value);
-  return writeJsonArtifact(
+  const artifact = await writeJsonArtifact(
     target,
     ARTIFACT_PATHS.route,
     value,
@@ -24,6 +27,10 @@ export async function persistRoute(target, route, packageRoot, options = {}) {
     packageRoot,
     writeOptions,
   );
+  if (contractArtifact && contractArtifact.fingerprint === artifact.value.contractFingerprint) {
+    await ensureResumableState({ target, packageRoot, contract: contractArtifact, route: artifact });
+  }
+  return artifact;
 }
 
 export async function readPersistedRoute(target, packageRoot) {

package/src/core/router.js

@@ -84,7 +84,7 @@ export const PLATFORM_SEMANTICS = Object.freeze({
 });
 
 const WORK_GUIDES = Object.freeze({
-  "complete-website": ["premium", "design", "accessibility", "clean", "test", "security", "performance"],
+  "complete-website": ["premium", "design", "taste", "accessibility", "clean", "test", "security", "performance"],
   "api-auth": ["clean", "test", "security", "performance"],
   api: ["clean", "test"],
   backend: ["clean", "test"],
@@ -240,6 +240,7 @@ export function evaluateRoute(input = {}) {
     else if (guide === "performance") excluded[guide] = ["NO_MEASURABLE_PERFORMANCE_RISK"];
     else if (guide === "design" || guide === "accessibility") excluded[guide] = ["NO_UI_SURFACE"];
     else if (guide === "premium" || guide === "games") excluded[guide] = ["NO_PRIMARY_WORK_TYPE"];
+    else if (guide === "taste") excluded[guide] = ["NO_TASTE_FRONTEND_CONTEXT"];
     else excluded[guide] = ["NO_BEHAVIOR_OR_EXECUTABLE_CHANGE"];
   }
 

package/src/core/target-layout.js

@@ -0,0 +1,38 @@
+export const LAYOUT_VERSION = 2;
+export const LEGACY_LAYOUT_VERSION = 1;
+export const FORGELOOP_DIR = ".forgeloop";
+export const FORGELOOP_KIT_DIR = ".forgeloop/kit";
+export const PROFILE_PATH = `${FORGELOOP_KIT_DIR}/PROJECT_PROFILE.md`;
+export const LEGACY_PROFILE_PATH = "PROJECT_PROFILE.md";
+
+export const NATIVE_ADAPTER_PATHS = Object.freeze([
+  "AGENTS.md",
+  "CLAUDE.md",
+  ".cursor/rules/project-loop.mdc",
+  ".github/copilot-instructions.md",
+]);
+
+const NATIVE_ADAPTER_SET = new Set(NATIVE_ADAPTER_PATHS);
+
+export function isNativeAdapterPath(relativePath) {
+  return NATIVE_ADAPTER_SET.has(relativePath);
+}
+
+export function targetPathForSource(sourcePath) {
+  if (sourcePath === ".forgeloop/.gitignore" || isNativeAdapterPath(sourcePath)) {
+    return sourcePath;
+  }
+  return `${FORGELOOP_KIT_DIR}/${sourcePath}`;
+}
+
+export function legacyPathForSource(sourcePath) {
+  return sourcePath === ".forgeloop/forgeloop.gitignore" ? ".forgeloop/.gitignore" : sourcePath;
+}
+
+export function isKitPath(relativePath) {
+  return relativePath === FORGELOOP_KIT_DIR || relativePath.startsWith(`${FORGELOOP_KIT_DIR}/`);
+}
+
+export function profilePathForLayout(layoutVersion = LAYOUT_VERSION) {
+  return layoutVersion >= LAYOUT_VERSION ? PROFILE_PATH : LEGACY_PROFILE_PATH;
+}

package/src/core/templates.js

@@ -2,6 +2,13 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import {
+  isNativeAdapterPath,
+  legacyPathForSource,
+  targetPathForSource,
+} from "./target-layout.js";
+import { nativeShim } from "./native-adapters.js";
+
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
 const TEMPLATE_SOURCE_PATHS = Object.freeze({
@@ -35,6 +42,7 @@ export const TEMPLATE_PATHS = [
   "ENG/games-code-design-web-eng.md",
   "ENG/perf-code-eng.md",
   "ENG/premium-sites-studio-eng.md",
+  "ENG/taste-frontend-eng.md",
   "ENG/sec-code-eng.md",
   "ENG/test-code-eng.md",
   "schemas/routing-input.schema.json",
@@ -66,8 +74,12 @@ export async function readTemplateEntries(packageRoot = PACKAGE_ROOT) {
     TEMPLATE_PATHS.map(async (relativePath) => {
       const sourcePath = TEMPLATE_SOURCE_PATHS[relativePath] ?? relativePath;
       return {
-        relativePath,
-        bytes: await readFile(path.join(packageRoot, sourcePath)),
+        relativePath: targetPathForSource(relativePath),
+        sourcePath,
+        legacyRelativePath: legacyPathForSource(sourcePath),
+        bytes: Buffer.from(isNativeAdapterPath(relativePath)
+          ? nativeShim(relativePath)
+          : await readFile(path.join(packageRoot, sourcePath))),
       };
     }),
   );