@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/core/phase.js

@@ -11,11 +11,16 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
 import { readWorkState, writeWorkState } from "./work-state.js";
 import { evaluateCompletion } from "./completion.js";
-import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
+import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
 import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
+import { taskArtifactPath } from "./task-paths.js";
+import { discoverTasks } from "./task-discovery.js";
+import { assertNoScopeConflicts, assertScopeClean } from "./task-scope.js";
+import { readTaskDescriptor } from "./task-descriptor.js";
+import { E_TASK_SCOPE_REQUIRED } from "./error-codes.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -44,15 +49,19 @@ const LATE_PHASES = new Set([
   "COMPLETE",
 ]);
 
-async function assertPersistedStateIdentity(target, state, toPhase, packageRoot) {
+async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+  const scopedTaskId = options.taskId ?? null;
   const requireContract = LATE_PHASES.has(state.phase)
     || ["CONTRACT_READY", "ROUTED", "EXECUTING"].includes(toPhase);
   const requireRoute = LATE_PHASES.has(state.phase)
     || ["ROUTED", "EXECUTING"].includes(toPhase);
+  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
+
   let contract = null;
   let route = null;
   try {
-    contract = await readContract(target, packageRoot);
+    contract = await readContract(target, packageRoot, { taskId: scopedTaskId, contractPath: options.contractPath });
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING" && !requireContract) {
       contract = null;
@@ -60,12 +69,12 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot)
       throw phaseError(
         requireContract ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_CONTRACT_INVALID",
         `${requireContract ? `Phase ${toPhase} requires current contract` : "Unable to validate current contract"}: ${error.message}`,
-        [ARTIFACT_PATHS.contract],
+        [contractRel],
       );
     }
   }
   try {
-    route = await readPersistedRoute(target, packageRoot);
+    route = await readPersistedRoute(target, packageRoot, { taskId: scopedTaskId, routePath: options.routePath });
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING" && !requireRoute) {
       route = null;
@@ -73,7 +82,7 @@ async function assertPersistedStateIdentity(target, state, toPhase, packageRoot)
       throw phaseError(
         requireRoute ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_ROUTE_INVALID",
         `${requireRoute ? `Phase ${toPhase} requires persisted route` : "Unable to validate persisted route"}: ${error.message}`,
-        [ARTIFACT_PATHS.route],
+        [routeRel],
       );
     }
   }
@@ -101,24 +110,28 @@ function reconcileImplementationStep(state, toPhase) {
   };
 }
 
-async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext) {
+async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, options = {}) {
+  const scopedTaskId = options.taskId ?? null;
+  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
+
   if (toPhase === "CONTRACT_READY" || toPhase === "ROUTED" || toPhase === "EXECUTING") {
     try {
-      await readContract(target, packageRoot);
+      await readContract(target, packageRoot, { taskId: scopedTaskId, contractPath: options.contractPath });
     } catch (error) {
-      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${ARTIFACT_PATHS.contract}: ${error.message}`, [ARTIFACT_PATHS.contract]);
+      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${contractRel}: ${error.message}`, [contractRel]);
     }
   }
   if (toPhase === "ROUTED" || toPhase === "EXECUTING") {
     try {
-      await readPersistedRoute(target, packageRoot);
+      await readPersistedRoute(target, packageRoot, { taskId: scopedTaskId, routePath: options.routePath });
     } catch (error) {
-      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${ARTIFACT_PATHS.route}: ${error.message}`, [ARTIFACT_PATHS.route]);
+      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${routeRel}: ${error.message}`, [routeRel]);
     }
   }
   if (hasExecutionStarted(toPhase)) {
     try {
-      await assertExecutionPrerequisites({ target, state, packageRoot });
+      await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId });
     } catch (error) {
       throw phaseError(error.code, error.message, error.artifacts);
     }
@@ -127,7 +140,7 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
     throw phaseError("E_PHASE_EVIDENCE_MISSING", "COMPLETE requires verification evidence");
   }
   if (toPhase === "COMPLETE") {
-    const completion = await evaluateCompletion({ target, packageRoot, persist: false, authorityContext, runtimeContext });
+    const completion = await evaluateCompletion({ target, packageRoot, persist: false, authorityContext, runtimeContext, taskId: scopedTaskId, ...options });
     if (completion.status !== "VALID") {
       throw phaseError("E_COMPLETION_REJECTED", "COMPLETE requires a valid completion audit", completion.errors.flatMap((error) => error.artifacts ?? []));
     }
@@ -141,37 +154,76 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     now = new Date().toISOString(),
     authorityContext,
     runtimeContext,
+    taskId = null,
+    statePath = null,
+    contractPath = null,
+    routePath = null,
+    receiptPath = null,
+    eventsPath = null,
   } = normalizedOptions;
   assertWorkPhase(toPhase);
-  const state = await readWorkState(target, packageRoot);
-  if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [ARTIFACT_PATHS.state]);
-  await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext);
-  await assertPersistedStateIdentity(target, state, toPhase, packageRoot);
+
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  const stateRel = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [stateRel]);
+
+  const eventsRel = eventsPath ?? (taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events);
+  const receiptRel = receiptPath ?? (taskId ? taskArtifactPath(taskId, "receipt") : ARTIFACT_PATHS.receipt);
+
+  await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, { taskId, statePath, contractPath, routePath, receiptPath, eventsPath });
+  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, { taskId, contractPath, routePath });
+
+  if (toPhase === "EXECUTING" && taskId) {
+    // Multi-task checkout scope checks
+    const discovered = await discoverTasks(target, packageRoot);
+    let descriptor = null;
+    try {
+      const descArtifact = await readTaskDescriptor(target, taskId, packageRoot);
+      descriptor = descArtifact.value;
+    } catch {
+      // Descriptor might not exist if legacy
+    }
+
+    const nonCompleteTasks = discovered.filter((t) => t.phase !== "COMPLETE");
+    if (nonCompleteTasks.length > 1) {
+      const claims = descriptor?.writeClaims ?? [];
+      if (claims.length === 0) {
+        throw phaseError(
+          E_TASK_SCOPE_REQUIRED,
+          "Multiple tasks exist in the repository. Entering EXECUTING requires declared non-empty write claims. Use 'forgeloop task-scope' first.",
+          [descriptor ? taskArtifactPath(taskId, "descriptor") : stateRel],
+        );
+      }
+      assertNoScopeConflicts(claims, discovered, taskId);
+      await assertScopeClean(target, claims);
+    }
+  }
+
   if (!isValidTransition(state.phase, toPhase)) {
     throw phaseError("E_PHASE_TRANSITION_INVALID", `Invalid work-state transition: ${state.phase} -> ${toPhase}`);
   }
-  const ledger = await validateEventLedger(target, packageRoot);
+  const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
   if (!ledger.valid) {
     const first = ledger.errors[0];
-    throw phaseError(first.code, first.message, [ARTIFACT_PATHS.events]);
+    throw phaseError(first.code, first.message, [eventsRel]);
   }
   if (ledger.events.some((event) => event.taskId !== state.taskId)) {
     throw phaseError(
       "E_PHASE_CHRONOLOGY_INVALID",
       "Cannot advance work state with lifecycle events from a different task",
-      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.state],
+      [eventsRel, stateRel],
     );
   }
   const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
   if (coherenceErrors.length > 0) {
-    throw phaseError(coherenceErrors[0].code, coherenceErrors[0].message, [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events]);
+    throw phaseError(coherenceErrors[0].code, coherenceErrors[0].message, [stateRel, eventsRel]);
   }
   const eventType = PHASE_EVENTS[toPhase];
   const reenteringVerification = toPhase === "VERIFYING" && ["CORRECTING", "REVIEWING"].includes(state.phase);
   if (toPhase === "VERIFYING" && state.phase === "REVIEWING") {
     let currentReceipt = null;
     try {
-      const receiptArtifact = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+      const receiptArtifact = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
       currentReceipt = receiptArtifact?.value;
     } catch {
       // If receipt is not present, pass null
@@ -186,7 +238,7 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       throw phaseError(
         firstError.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
         firstError.message ?? "REVIEWING -> VERIFYING requires authorized completion recovery",
-        [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+        [stateRel, eventsRel],
       );
     }
   }
@@ -195,7 +247,7 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       throw phaseError(
         "E_PHASE_PREREQUISITE_MISSING",
         "CORRECTING -> VERIFYING requires a diagnosed hypothesis",
-        [ARTIFACT_PATHS.state],
+        [stateRel],
       );
     }
   }
@@ -203,13 +255,13 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === "REVIEW_STARTED");
   if (eventType && !reenteringVerification && !repeatedReview
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === eventType)) {
-    throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [ARTIFACT_PATHS.events]);
+    throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [eventsRel]);
   }
   const milestoneIndex = reenteringVerification || repeatedReview ? -1 : LIFECYCLE_MILESTONES.indexOf(eventType);
   if (milestoneIndex >= 0) {
     const lastMilestone = ledger.events.reduce((last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)), -1);
     if (lastMilestone !== milestoneIndex - 1) {
-      throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Phase ${toPhase} cannot append ${eventType} after the current lifecycle ledger`, [ARTIFACT_PATHS.events]);
+      throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Phase ${toPhase} cannot append ${eventType} after the current lifecycle ledger`, [eventsRel]);
     }
   }
   const reconciled = reconcileImplementationStep(state, toPhase);
@@ -225,10 +277,10 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   if (reenteringVerification) delete next.lastCompletionAttempt;
   let nextReceipt = null;
   try {
-    const receipt = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
-    const contract = await readContract(target, packageRoot);
-    const route = await readPersistedRoute(target, packageRoot);
-    const preflight = await evaluatePreflight({ target, packageRoot });
+    const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+    const contract = await readContract(target, packageRoot, { taskId, contractPath });
+    const route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
+    const preflight = await evaluatePreflight({ target, packageRoot, taskId, contractPath, routePath, statePath });
     const requiredEvidence = await requiredEvidenceForTarget({
       target,
       contract,
@@ -280,9 +332,9 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   } catch (error) {
     if (error.code !== "ARTIFACT_MISSING") throw error;
   }
-  await writeWorkState(target, next, { packageRoot });
+  await writeWorkState(target, next, { packageRoot, taskId, statePath });
   if (nextReceipt) {
-    await writeJsonArtifact(target, ARTIFACT_PATHS.receipt, nextReceipt, "execution-receipt", packageRoot);
+    await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
   }
   if (eventType) await appendProtocolEvent(target, {
     taskId: state.taskId,
@@ -293,6 +345,6 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       : eventType === "REVIEW_STARTED"
         ? { verificationCycle: next.verificationCycle ?? 1 }
         : undefined,
-  }, packageRoot);
+  }, packageRoot, { taskId, eventsPath });
   return next;
 }

package/src/core/preflight-consistency.js

@@ -14,6 +14,8 @@ import {
   validatePersistedPreflight,
 } from "./preflight-model.js";
 
+import { taskArtifactPath } from "./task-paths.js";
+
 async function readOptionalIdentityArtifact(readArtifact, invalidCode, artifactPath) {
   try {
     return await readArtifact();
@@ -23,36 +25,44 @@ async function readOptionalIdentityArtifact(readArtifact, invalidCode, artifactP
   }
 }
 
-export async function assertPreflightPersistenceSafety(target, packageRoot, taskId) {
+export async function assertPreflightPersistenceSafety(target, packageRoot, taskIdOrOptions = {}, maybeOptions = {}) {
+  const options = typeof taskIdOrOptions === "object" && taskIdOrOptions !== null ? taskIdOrOptions : maybeOptions;
+  const taskId = typeof taskIdOrOptions === "string" ? taskIdOrOptions : (options.taskId ?? null);
+  const contractRel = options.contractPath ?? (taskId && taskId !== "unknown" ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (taskId && taskId !== "unknown" ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
+  const stateRel = options.statePath ?? (taskId && taskId !== "unknown" ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const eventsRel = options.eventsPath ?? (taskId && taskId !== "unknown" ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events);
+
   let state;
   try {
-    state = await readWorkState(target, packageRoot);
+    state = await readWorkState(target, { packageRoot, taskId, statePath: options.statePath });
   } catch (error) {
-    throw preflightError("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]);
+    throw preflightError("E_STATE_INVALID", error.message, [stateRel]);
   }
   const contract = await readOptionalIdentityArtifact(
-    () => readContract(target, packageRoot),
+    () => readContract(target, packageRoot, { taskId, contractPath: options.contractPath }),
     "E_CONTRACT_INVALID",
-    ARTIFACT_PATHS.contract,
+    contractRel,
   );
   const route = await readOptionalIdentityArtifact(
-    () => readPersistedRoute(target, packageRoot),
+    () => readPersistedRoute(target, packageRoot, { taskId, routePath: options.routePath }),
     "E_ROUTE_INVALID",
-    ARTIFACT_PATHS.route,
+    routeRel,
   );
   if (state && (contract || route)) assertStateIdentity({ contract, route, state });
 
-  if (taskId === "unknown") return null;
-  const ledger = await validateEventLedger(target, packageRoot);
+  const effectiveTaskId = taskId ?? contract?.value?.taskId ?? state?.taskId ?? null;
+  if (effectiveTaskId === "unknown" || !effectiveTaskId) return null;
+  const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath: options.eventsPath });
   if (!ledger.valid) {
     const first = ledger.errors[0];
-    throw preflightError(first.code, first.message, [ARTIFACT_PATHS.events]);
+    throw preflightError(first.code, first.message, [eventsRel]);
   }
-  if (ledger.events.some((event) => event.taskId !== taskId)) {
+  if (ledger.events.some((event) => event.taskId !== effectiveTaskId)) {
     throw preflightError(
       "E_PHASE_CHRONOLOGY_INVALID",
       "Preflight cannot append events to a ledger owned by a different task",
-      [ARTIFACT_PATHS.events, ARTIFACT_PATHS.contract],
+      [eventsRel, contractRel],
     );
   }
   return ledger;
@@ -159,11 +169,11 @@ export function assertExistingReadyLifecycleCompatibility(ledger, result) {
   }
 }
 
-export async function appendActivationEvents(target, packageRoot, ledger, result) {
+export async function appendActivationEvents(target, packageRoot, ledger, result, options = {}) {
   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);
+    const event = await appendProtocolEvent(target, input, packageRoot, options);
     events.push(event);
   };
 

package/src/core/preflight-loaders.js

@@ -6,8 +6,9 @@ import { assertSourceProvenance } from "./sources.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { ensureWithin, readBytes } from "./filesystem.js";
 import { sha256 } from "./manifest.js";
-import { findProfilePath, validateProfileSources } from "./profile.js";
+import { findProfilePath } from "./profile.js";
 import { issue } from "./preflight-model.js";
+import { taskGatePath, taskArtifactPath } from "./task-paths.js";
 
 export async function readProfile(target) {
   const relativePath = await findProfilePath(target);
@@ -36,23 +37,25 @@ export async function optionalConfig(target, packageRoot, errors) {
   }
 }
 
-export async function loadContract(target, packageRoot, errors) {
+export async function loadContract(target, packageRoot, errors, options = {}) {
   try {
-    return await readContract(target, packageRoot);
+    return await readContract(target, packageRoot, options);
   } catch (error) {
-    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_CONTRACT_MISSING" : "E_CONTRACT_INVALID", error.message, [ARTIFACT_PATHS.contract]));
+    const path = options.contractPath ?? (options.taskId ? taskArtifactPath(options.taskId, "contract") : ARTIFACT_PATHS.contract);
+    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_CONTRACT_MISSING" : "E_CONTRACT_INVALID", error.message, [path]));
     return null;
   }
 }
 
-export async function loadRoute(target, packageRoot, errors) {
+export async function loadRoute(target, packageRoot, errors, options = {}) {
   try {
-    return await readPersistedRoute(target, packageRoot);
+    return await readPersistedRoute(target, packageRoot, options);
   } catch (error) {
+    const path = options.routePath ?? (options.taskId ? taskArtifactPath(options.taskId, "route") : ARTIFACT_PATHS.route);
     const code = error.code === "ARTIFACT_MISSING"
       ? "E_ROUTE_MISSING"
       : ["E_ROUTE_REASON_MISSING", "E_ROUTE_INVALID"].includes(error.code) ? error.code : "E_ROUTE_INVALID";
-    errors.push(issue(code, error.message, [ARTIFACT_PATHS.route]));
+    errors.push(issue(code, error.message, [path]));
     return null;
   }
 }
@@ -74,22 +77,24 @@ export async function loadSources(target, contract, packageRoot, errors) {
   return registry;
 }
 
-export async function inspectGates(target, contract, route, packageRoot, errors, config = {}) {
+export async function inspectGates(target, contract, route, packageRoot, errors, config = {}, options = {}) {
   if (!route) return { required: [], satisfied: [], records: {} };
   const guideGates = await requiredGatesForGuides(route.value.guides, packageRoot);
   const required = [...new Set([...guideGates, ...(config.requiredGates ?? [])])].sort();
   const satisfied = [];
   const records = {};
+  const taskId = options.taskId ?? null;
   for (const gate of required) {
     let artifact;
+    const defaultGateRel = taskId ? taskGatePath(taskId, gate) : `${ARTIFACT_PATHS.gates}/${gate}.json`;
     try {
-      artifact = await readGateIfPresent(target, gate, packageRoot);
+      artifact = await readGateIfPresent(target, gate, packageRoot, { ...options, taskId });
     } catch (error) {
-      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID", error.message, [`${ARTIFACT_PATHS.gates}/${gate}.json`], { gate }));
+      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID", error.message, [defaultGateRel], { gate }));
       continue;
     }
     if (!artifact) {
-      errors.push(issue("E_GATE_UNVERIFIED", `Required gate is missing or unverified: ${gate}`, [`${ARTIFACT_PATHS.gates}/${gate}.json`], { gate }));
+      errors.push(issue("E_GATE_UNVERIFIED", `Required gate is missing or unverified: ${gate}`, [defaultGateRel], { gate }));
       continue;
     }
     records[gate] = artifact;

package/src/core/preflight.js

@@ -8,7 +8,6 @@ import {
   issue,
   preflightError,
   sortIssues,
-  validatePersistedPreflight,
 } from "./preflight-model.js";
 import {
   loadContract,
@@ -28,31 +27,36 @@ import {
 import { PROFILE_PATH } from "./target-layout.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { validateEventLedger } from "./events.js";
+import { taskArtifactPath } from "./task-paths.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
 
 export { validatePersistedPreflight } from "./preflight-model.js";
 
-export async function evaluatePreflight({ target, packageRoot, strict = false } = {}) {
+export async function evaluatePreflight({ target, packageRoot, strict = false, taskId = null, contractPath = null, routePath = null, statePath = null } = {}) {
   const errors = [];
   const profile = await readProfile(target);
   const profileProvenance = await validateProfileSources(target, packageRoot);
   errors.push(...(profileProvenance.errors ?? []));
-  const contract = await loadContract(target, packageRoot, errors);
-  const route = await loadRoute(target, packageRoot, errors);
+  const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath });
+  const route = await loadRoute(target, packageRoot, errors, { taskId, routePath });
   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", [PROFILE_PATH]));
   }
 
+  const contractRelPath = contractPath ?? (taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRelPath = routePath ?? (taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route);
+  const stateRelPath = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+
   const unresolvedDecisions = contract?.value?.unresolvedDecisions ?? [];
   if (unresolvedDecisions.length > 0) {
     errors.push(issue(
       "E_CONTRACT_UNRESOLVED_DECISION",
       "The current contract contains unresolved blocking decisions.",
-      [ARTIFACT_PATHS.contract],
+      [contractRelPath],
       {
         decisions: unresolvedDecisions
           .slice(0, PREVIEW_DECISION_LIMIT)
@@ -67,32 +71,32 @@ export async function evaluatePreflight({ target, packageRoot, strict = false }
   if (route && contract) {
     assertRouteInvariants(route.value);
     if (route.value.contractFingerprint !== undefined && route.value.contractFingerprint !== contract.fingerprint) {
-      errors.push(issue("E_ROUTE_STALE", "Routing result was created for a different contract", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.contract]));
+      errors.push(issue("E_ROUTE_STALE", "Routing result was created for a different contract", [routeRelPath, contractRelPath]));
     }
   }
 
   const sources = await loadSources(target, contract, packageRoot, errors);
-  const gates = await inspectGates(target, contract, route, packageRoot, errors, config);
+  const gates = await inspectGates(target, contract, route, packageRoot, errors, config, { taskId });
 
   let state = null;
   try {
-    state = await readWorkState(target, packageRoot);
+    state = await readWorkState(target, { packageRoot, taskId, statePath });
   } catch (error) {
-    errors.push(issue("E_STATE_INVALID", error.message, [ARTIFACT_PATHS.state]));
+    errors.push(issue("E_STATE_INVALID", error.message, [stateRelPath]));
   }
   if (state && route && JSON.stringify(state.selectedGuides) !== JSON.stringify(route.value.guides)) {
-    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "work-state.selectedGuides must equal routing-result.guides", [ARTIFACT_PATHS.route, ARTIFACT_PATHS.state]));
+    errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "work-state.selectedGuides must equal routing-result.guides", [routeRelPath, stateRelPath]));
   }
   if (state && contract && state.contractFingerprint !== contract.fingerprint) {
-    errors.push(issue("E_CONTRACT_STALE", "work-state references a different contract", [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.state]));
+    errors.push(issue("E_CONTRACT_STALE", "work-state references a different contract", [contractRelPath, stateRelPath]));
   }
 
   const sortedErrors = sortIssues(errors);
-  const taskId = contract?.value?.taskId ?? state?.taskId ?? "unknown";
+  const effectiveTaskId = taskId ?? contract?.value?.taskId ?? state?.taskId ?? "unknown";
   return {
     schemaVersion: 1,
     protocolVersion: 1,
-    taskId,
+    taskId: effectiveTaskId,
     status: sortedErrors.length === 0 ? "READY" : "BLOCKED",
     profile: { ...profile, provenance: profileProvenance.status },
     contract: contract
@@ -128,20 +132,31 @@ export async function validateReadyProtocolConsistency(options = {}) {
   });
 }
 
-export async function runPreflight({ target, packageRoot, strict = false, persist = true } = {}) {
-  let result = await evaluatePreflight({ target, packageRoot, strict });
+export async function runPreflight({
+  target,
+  packageRoot,
+  strict = false,
+  persist = true,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  preflightPath = null,
+  eventsPath = null,
+} = {}) {
+  let result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
   if (!persist) return result;
 
-  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
+  let ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
   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 });
+    contract = await readContract(target, packageRoot, { taskId, contractPath });
+    route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
+    const state = await ensureResumableState({ target, packageRoot, contract, route, taskId, statePath });
     if (state) {
       await synchronizePreflightState({
         target,
@@ -152,22 +167,26 @@ export async function runPreflight({ target, packageRoot, strict = false, persis
         requiredGates: result.requiredGates,
         satisfiedGates: result.satisfiedGates,
         complianceMode: result.policy?.complianceMode,
+        statePath,
+        taskId,
       });
-      result = await evaluatePreflight({ target, packageRoot, strict });
+      result = await evaluatePreflight({ target, packageRoot, strict, taskId, contractPath, routePath, statePath });
       assertPreflightResultPersistenceSafety(result);
       assertExistingReadyLifecycleCompatibility(ledger, result);
-      ledger = await assertPreflightPersistenceSafety(target, packageRoot, result.taskId);
+      ledger = await assertPreflightPersistenceSafety(target, packageRoot, { taskId, eventsPath });
     }
   }
 
   if (result.taskId !== "unknown") {
-    await appendActivationEvents(target, packageRoot, ledger, result);
-    const afterEvents = await validateEventLedger(target, packageRoot);
+    await appendActivationEvents(target, packageRoot, ledger, result, { eventsPath, taskId });
+    const afterEvents = await validateEventLedger(target, packageRoot, { eventsPath, taskId });
     if (!afterEvents.valid) {
       const first = afterEvents.errors[0];
-      throw preflightError(first.code, first.message, [ARTIFACT_PATHS.events]);
+      const evRel = eventsPath ?? (taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events);
+      throw preflightError(first.code, first.message, [evRel]);
     }
   }
-  await writeJsonArtifact(target, ARTIFACT_PATHS.preflight, result, "preflight", packageRoot);
+  const relPath = preflightPath ?? (taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight);
+  await writeJsonArtifact(target, relPath, result, "preflight", packageRoot);
   return result;
 }

package/src/core/protocol.js

@@ -111,17 +111,8 @@ export const WORK_PHASES = Object.freeze([
   "BLOCKED",
 ]);
 
-export const GUIDE_IDS = Object.freeze([
-  "premium",
-  "clean",
-  "test",
-  "security",
-  "design",
-  "performance",
-  "accessibility",
-  "games",
-  "taste",
-]);
+import { GUIDE_IDS } from "./guide-registry.js";
+export { GUIDE_IDS };
 
 export const GUIDE_ORDER = GUIDE_IDS;
 

package/src/core/receipt.js

@@ -2,7 +2,7 @@ import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { assertEvidenceList, evidenceMatches } from "./evidence.js";
 import { assertJsonLimits } from "./json-safety.js";
-import { assertCheck, assertCheckList } from "./checks.js";
+import { assertCheck } from "./checks.js";
 import { assertCoverageList } from "./coverage.js";
 
 const RECEIPT_SCHEMA_VERSION = 1;

package/src/core/report.js

@@ -17,8 +17,8 @@ function section(id, label, status, details = null) {
   return { id, label, status, ...(details ? { details } : {}) };
 }
 
-export async function evaluateReport({ target, packageRoot, strict = false } = {}) {
-  const audit = await evaluateAudit({ target, packageRoot, strict });
+export async function evaluateReport({ target, packageRoot, strict = false, ...options } = {}) {
+  const audit = await evaluateAudit({ target, packageRoot, strict, ...options });
   const completion = audit.completion;
   const preflight = completion.preflight;
   const errorCodes = new Set(audit.errors.map((error) => error.code));