@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/core/completion-artifacts.js

@@ -18,9 +18,13 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { readWorkState, writeWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
-import { normalizeRequirements, classifyRequirement } from "./evidence-readiness.js";
+import { normalizeRequirements } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
 import { readExecutionArtifact, validateExecutionBinding } from "./execution.js";
+import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
+import { readTaskDescriptor } from "./task-descriptor.js";
+import { assertClaimsCoverChangedPaths } from "./task-scope.js";
+import { discoverTasks } from "./task-discovery.js";
 
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -36,15 +40,16 @@ function requiredString(value, label) {
   return value;
 }
 
-async function readCurrentReceipt(target, packageRoot) {
+async function readCurrentReceipt(target, packageRoot, options = {}) {
+  const receiptRel = options.receiptPath ?? (options.taskId ? taskArtifactPath(options.taskId, "receipt") : ARTIFACT_PATHS.receipt);
   try {
-    return await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+    return await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING") {
       throw artifactError(
         "E_RECEIPT_MISSING",
         "Execution receipt is missing; run forgeloop prepare-completion first",
-        [ARTIFACT_PATHS.receipt],
+        [receiptRel],
       );
     }
     throw error;
@@ -92,12 +97,13 @@ export async function validateCheckExecutionProvenance(check, {
       target,
       executionRef: check.executionRef,
       packageRoot,
+      taskId,
     });
   if (!artifact.value) {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",
       "Execution reference does not resolve to an execution artifact in this bundle",
-      [ARTIFACT_PATHS.executionDirectory],
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
   const execution = validateExecutionBinding({
@@ -111,52 +117,51 @@ export async function validateCheckExecutionProvenance(check, {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",
       "Execution artifact cwd does not match the current target",
-      [ARTIFACT_PATHS.executionDirectory],
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
   if (check.status === "passed" && (execution.status !== "passed" || execution.exitCode !== 0)) {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",
       "A passed command check must reference a successful execution artifact",
-      [ARTIFACT_PATHS.executionDirectory],
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
   if (check.status === "failed" && execution.status !== "failed") {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",
       "A failed command check must reference a failed execution artifact",
-      [ARTIFACT_PATHS.executionDirectory],
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
   if (check.exitCode !== undefined && check.exitCode !== execution.exitCode) {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",
       "Check exitCode does not match its execution artifact",
-      [ARTIFACT_PATHS.executionDirectory],
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
   return execution;
 }
 
-export async function validateChecksExecutionProvenance(checks, options = {}) {
-  const errors = [];
-  for (const check of Array.isArray(checks) ? checks : []) {
-    try {
-      await validateCheckExecutionProvenance(check, options);
-    } catch (error) {
-      errors.push({
-        code: error.code ?? "E_EXECUTION_REF_INVALID",
-        message: error.message,
-        artifacts: error.artifacts ?? [options.artifactPath ?? ARTIFACT_PATHS.receipt],
-        checkId: check?.id,
-        requirementId: check?.requirement,
-      });
+export async function validateChecksExecutionProvenance(checks, options) {
+  const executions = [];
+  for (const check of checks ?? []) {
+    if (check.kind === "command" && check.evidenceKind === "OBSERVED") {
+      const execution = await validateCheckExecutionProvenance(check, options);
+      if (execution) executions.push(execution);
     }
   }
-  return errors;
+  return executions;
 }
 
-export async function requiredEvidenceForTarget({ target, contract, route, packageRoot, additionalEvidence = [] }) {
+export async function requiredEvidenceForTarget({
+  target,
+  contract,
+  route,
+  packageRoot,
+  additionalEvidence = [],
+}) {
   const config = await readOptionalConfig(target, packageRoot);
   const guideEvidence = await completionEvidenceForGuides(route.value.guides, packageRoot);
   return [...new Set([
@@ -167,23 +172,36 @@ export async function requiredEvidenceForTarget({ target, contract, route, packa
   ])].sort();
 }
 
-export async function prepareCompletion({ target, packageRoot, authorityContext, runtimeContext }) {
-  const contract = await readContract(target, packageRoot);
-  const route = await readPersistedRoute(target, packageRoot);
-  const state = await readWorkState(target, packageRoot);
+export async function prepareCompletion({
+  target,
+  packageRoot,
+  authorityContext,
+  runtimeContext,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  receiptPath = null,
+}) {
+  const contract = await readContract(target, packageRoot, { taskId, contractPath });
+  const route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  const stateRel = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const receiptRel = receiptPath ?? (taskId ? taskArtifactPath(taskId, "receipt") : ARTIFACT_PATHS.receipt);
+
   if (!state) {
-    throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [ARTIFACT_PATHS.state]);
+    throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [stateRel]);
   }
   if (hasExecutionStarted(state.phase)) {
-    await assertExecutionPrerequisites({ target, state, packageRoot });
+    await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
   }
 
   let existing = null;
   try {
-    existing = await readJsonArtifact(target, ARTIFACT_PATHS.receipt, "execution-receipt", packageRoot);
+    existing = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
     await validateReceipt(existing.value, packageRoot, {
       target,
-      taskId: contract?.value?.taskId,
+      taskId: contract.value.taskId,
       authorityContext,
       runtimeContext,
     });
@@ -191,7 +209,7 @@ export async function prepareCompletion({ target, packageRoot, authorityContext,
     if (error.code !== "ARTIFACT_MISSING") throw error;
   }
 
-  const preflight = await evaluatePreflight({ target, packageRoot });
+  const preflight = await evaluatePreflight({ target, packageRoot, taskId, contractPath, routePath, statePath });
   const requiredEvidence = await requiredEvidenceForTarget({
     target,
     contract,
@@ -201,13 +219,46 @@ export async function prepareCompletion({ target, packageRoot, authorityContext,
   });
   const existingValue = existing?.value ?? {};
   if (existingValue.taskId && existingValue.taskId !== contract.value.taskId) {
-    throw artifactError("E_RECEIPT_TASK_MISMATCH", "Execution receipt does not belong to the current contract task", [ARTIFACT_PATHS.receipt]);
+    throw artifactError("E_RECEIPT_TASK_MISMATCH", "Execution receipt does not belong to the current contract task", [receiptRel]);
   }
   if (existing && existingValue.stateFingerprint === undefined) {
-    throw artifactError("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [ARTIFACT_PATHS.receipt]);
+    throw artifactError("E_RECEIPT_STATE_MISMATCH", "Execution receipt requires the current work-state fingerprint", [receiptRel]);
   }
   assertStateIdentity({ contract, route, state });
-  const observedPaths = await currentChangedPaths(target);
+
+  let writeClaims = [];
+  try {
+    const desc = taskId ? await readTaskDescriptor(target, taskId, packageRoot) : null;
+    writeClaims = desc?.value?.writeClaims ?? [];
+  } catch {
+    // descriptor may not exist
+  }
+
+  let observedPaths = null;
+  if (writeClaims.length > 0) {
+    observedPaths = await currentChangedPaths(target, { paths: writeClaims });
+    if (observedPaths !== null) {
+      assertClaimsCoverChangedPaths(writeClaims, observedPaths);
+    }
+  } else {
+    observedPaths = await currentChangedPaths(target);
+  }
+
+  if (observedPaths === null) {
+    const allTasks = await discoverTasks(target, packageRoot);
+    const nonComplete = allTasks.filter((t) => t.phase !== "COMPLETE");
+    if (nonComplete.length > 1) {
+      const mode = preflight.policy?.complianceMode ?? "standard";
+      if (mode === "standard" || mode === "strict") {
+        throw artifactError(
+          "E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE",
+          "Cannot attribute changed files across multiple concurrent tasks in a non-Git target",
+          [receiptRel],
+        );
+      }
+    }
+  }
+
   const changedPaths = observedPaths !== null
     ? [...observedPaths]
     : existing
@@ -264,7 +315,7 @@ export async function prepareCompletion({ target, packageRoot, authorityContext,
   });
   const written = await writeJsonArtifact(
     target,
-    ARTIFACT_PATHS.receipt,
+    receiptRel,
     receipt,
     "execution-receipt",
     packageRoot,
@@ -306,24 +357,33 @@ export async function assertRecordCheckPrerequisites({
   evidenceKind,
   authorityContext,
   runtimeContext,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
 } = {}) {
-  const state = await readWorkState(target, packageRoot);
-  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a check", [ARTIFACT_PATHS.state]);
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  const stateRel = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const eventsRel = eventsPath ?? (taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events);
+
+  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a check", [stateRel]);
   if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
-    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a check in ${state.phase}`, [ARTIFACT_PATHS.state]);
+    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a check in ${state.phase}`, [stateRel]);
   }
   if (state.phase !== "VERIFYING") {
     throw artifactError(
       "E_PHASE_PREREQUISITE_MISSING",
       `record-check requires VERIFYING before review; found ${state.phase}`,
-      [ARTIFACT_PATHS.state],
+      [stateRel],
     );
   }
-  await assertExecutionPrerequisites({ target, state, packageRoot });
+  await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
 
-  const contract = await readContract(target, packageRoot);
-  const route = await readPersistedRoute(target, packageRoot);
-  const preflight = await evaluatePreflight({ target, 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,
@@ -338,27 +398,27 @@ export async function assertRecordCheckPrerequisites({
     throw artifactError(
       "E_FUTURE_LIFECYCLE_EVIDENCE",
       `Terminal-owned requirement cannot be recorded before its authoritative result: ${requested.text}`,
-      [ARTIFACT_PATHS.state, ARTIFACT_PATHS.events],
+      [stateRel, eventsRel],
     );
   }
 
-  const existingReceipt = await readCurrentReceipt(target, packageRoot);
+  const existingReceipt = await readCurrentReceipt(target, packageRoot, { taskId, receiptPath });
   await validateReceipt(existingReceipt.value, packageRoot, {
     target,
     taskId: contract.value.taskId,
     authorityContext,
     runtimeContext,
   });
-  const ledger = await validateEventLedger(target, packageRoot);
+  const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
   if (!ledger.valid) {
     const first = ledger.errors[0];
-    throw artifactError(first.code, first.message, [ARTIFACT_PATHS.events]);
+    throw artifactError(first.code, first.message, [eventsRel]);
   }
   if (!ledger.events.some((event) => event.taskId === state.taskId && event.event === "VERIFICATION_STARTED")) {
     throw artifactError(
       "E_PHASE_CHRONOLOGY_INVALID",
       "record-check requires VERIFICATION_STARTED in the current task ledger",
-      [ARTIFACT_PATHS.events],
+      [eventsRel],
     );
   }
   return {
@@ -388,6 +448,12 @@ export async function recordCheck({
   provenance,
   authorityContext,
   runtimeContext,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
 }) {
   requiredString(id, "check id");
   requiredString(kind, "check kind");
@@ -422,6 +488,12 @@ export async function recordCheck({
     evidenceKind,
     authorityContext,
     runtimeContext,
+    taskId,
+    contractPath,
+    routePath,
+    statePath,
+    receiptPath,
+    eventsPath,
   });
   const {
     state,
@@ -431,6 +503,8 @@ export async function recordCheck({
     existingReceipt,
   } = context;
 
+  const receiptRel = receiptPath ?? (taskId ? taskArtifactPath(taskId, "receipt") : ARTIFACT_PATHS.receipt);
+
   const commandSpec = typeof command === "string" && command.trim() !== "" ? command.trim() : undefined;
   const observedCommand = kind === "command" && evidenceKind === "OBSERVED";
   if (observedCommand && (!executionRef || provenance !== "FORGELOOP_EXECUTED")) {
@@ -525,7 +599,7 @@ export async function recordCheck({
       runtimeContext,
     });
     if (!auth.valid) {
-      throw artifactError(auth.error.code, auth.error.message, [ARTIFACT_PATHS.receipt]);
+      throw artifactError(auth.error.code, auth.error.message, [receiptRel]);
     }
   }
 
@@ -582,10 +656,10 @@ export async function recordCheck({
     runtimeContext,
   });
 
-  await writeWorkState(target, nextState, { packageRoot });
+  await writeWorkState(target, nextState, { packageRoot, taskId, statePath });
   const written = await writeJsonArtifact(
     target,
-    ARTIFACT_PATHS.receipt,
+    receiptRel,
     nextReceipt,
     "execution-receipt",
     packageRoot,
@@ -600,7 +674,7 @@ export async function recordCheck({
       evidenceKind: check.evidenceKind,
       verificationCycle: state.verificationCycle ?? 1,
     },
-  }, packageRoot);
+  }, packageRoot, { taskId, eventsPath });
   return {
     path: written.path,
     receipt: written.value,
@@ -622,6 +696,12 @@ export async function recordTerminalResult({
   details = {},
   authorityContext,
   runtimeContext,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
 } = {}) {
   if (!target || !requirement || !type || !status || !source || !result) {
     throw artifactError("E_CHECK_INVALID", "record-terminal-result requires target, requirement, type, status, source, and result", [ARTIFACT_PATHS.state]);
@@ -636,16 +716,19 @@ export async function recordTerminalResult({
     throw artifactError("E_CHECK_INVALID", `Invalid production readiness status for record-terminal-result: ${status}`, [ARTIFACT_PATHS.state]);
   }
 
-  const state = await readWorkState(target, packageRoot);
-  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a terminal result", [ARTIFACT_PATHS.state]);
+  const state = await readWorkState(target, { packageRoot, taskId, statePath });
+  const stateRel = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
+  const receiptRel = receiptPath ?? (taskId ? taskArtifactPath(taskId, "receipt") : ARTIFACT_PATHS.receipt);
+
+  if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a terminal result", [stateRel]);
   if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
-    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a terminal result in ${state.phase}`, [ARTIFACT_PATHS.state]);
+    throw artifactError("E_PHASE_TRANSITION_INVALID", `Cannot record a terminal result in ${state.phase}`, [stateRel]);
   }
-  await assertExecutionPrerequisites({ target, state, packageRoot });
+  await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
 
-  const contract = await readContract(target, packageRoot);
-  const route = await readPersistedRoute(target, packageRoot);
-  const preflight = await evaluatePreflight({ target, 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,
@@ -663,7 +746,7 @@ export async function recordTerminalResult({
     throw artifactError(
       "E_TERMINAL_REQUIREMENT_UNKNOWN",
       `Terminal results must reference an existing canonical terminal requirement: ${requirement}`,
-      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+      [contractRelPath(contract, taskId), receiptRel],
     );
   }
 
@@ -671,7 +754,7 @@ export async function recordTerminalResult({
     throw artifactError(
       "E_TERMINAL_REQUIREMENT_NOT_TERMINAL",
       `record-terminal-result may only target terminal-owned requirements; found ${requested.type}: ${requested.text}`,
-      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+      [contractRelPath(contract, taskId), receiptRel],
     );
   }
 
@@ -679,11 +762,11 @@ export async function recordTerminalResult({
     throw artifactError(
       "E_TERMINAL_REQUIREMENT_TYPE_MISMATCH",
       `Requirement ${requested.id} is ${requested.type}, not ${type}.`,
-      [ARTIFACT_PATHS.contract, ARTIFACT_PATHS.receipt],
+      [contractRelPath(contract, taskId), receiptRel],
     );
   }
 
-  const existingReceipt = await readCurrentReceipt(target, packageRoot);
+  const existingReceipt = await readCurrentReceipt(target, packageRoot, { taskId, receiptPath });
   await validateReceipt(existingReceipt.value, packageRoot, {
     target,
     taskId: contract?.value?.taskId,
@@ -704,7 +787,7 @@ export async function recordTerminalResult({
       throw artifactError(
         "E_TERMINAL_STATUS_REGRESSION",
         `Publication status cannot regress from ${prev} to ${status}.`,
-        [ARTIFACT_PATHS.receipt],
+        [receiptRel],
       );
     }
   }
@@ -723,7 +806,7 @@ export async function recordTerminalResult({
   ));
 
   if (isIdentical) {
-    const ledger = await validateEventLedger(target, packageRoot);
+    const ledger = await validateEventLedger(target, packageRoot, { taskId, eventsPath });
     const matchingEvent = ledger.events.find((event) => (
       event.taskId === state.taskId
       && event.event === "TERMINAL_RESULT_RECORDED"
@@ -737,7 +820,7 @@ export async function recordTerminalResult({
 
     if (matchingEvent) {
       return {
-        path: path.join(target, ARTIFACT_PATHS.receipt),
+        path: path.join(target, receiptRel),
         receipt: existingReceipt.value,
         requirementId: requested.id,
         type,
@@ -759,10 +842,10 @@ export async function recordTerminalResult({
         source: source.trim(),
         result: result.trim(),
       },
-    }, packageRoot);
+    }, packageRoot, { taskId, eventsPath });
 
     return {
-      path: path.join(target, ARTIFACT_PATHS.receipt),
+      path: path.join(target, receiptRel),
       receipt: existingReceipt.value,
       requirementId: requested.id,
       type,
@@ -823,10 +906,10 @@ export async function recordTerminalResult({
     runtimeContext,
   });
 
-  await writeWorkState(target, nextState, { packageRoot });
+  await writeWorkState(target, nextState, { packageRoot, taskId, statePath });
   await writeJsonArtifact(
     target,
-    ARTIFACT_PATHS.receipt,
+    receiptRel,
     nextReceipt,
     "execution-receipt",
     packageRoot,
@@ -843,10 +926,10 @@ export async function recordTerminalResult({
       source: source.trim(),
       result: result.trim(),
     },
-  }, packageRoot);
+  }, packageRoot, { taskId, eventsPath });
 
   return {
-    path: path.join(target, ARTIFACT_PATHS.receipt),
+    path: path.join(target, receiptRel),
     receipt: nextReceipt,
     requirementId: requested.id,
     type,
@@ -855,3 +938,7 @@ export async function recordTerminalResult({
     event,
   };
 }
+
+function contractRelPath(contract, taskId) {
+  return taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
+}