@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/src/core/completion-artifacts.js

@@ -8,7 +8,7 @@ import {
 import { readContract } from "./contract.js";
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
 import { completionEvidenceForGuides } from "./guide-metadata.js";
-import { createCheck } from "./checks.js";
+import { CHECK_PROVENANCE, createCheck } from "./checks.js";
 import { createEvidence } from "./evidence.js";
 import { coverageForRequirements } from "./coverage.js";
 import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
@@ -20,6 +20,7 @@ import { readWorkState, writeWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { normalizeRequirements, classifyRequirement } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
+import { readExecutionArtifact, validateExecutionBinding } from "./execution.js";
 
 function artifactError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -59,6 +60,102 @@ async function readOptionalConfig(target, packageRoot) {
   }
 }
 
+function formatArgv(argv) {
+  return argv.map((argument) => /[\s"']/u.test(argument)
+    ? JSON.stringify(argument)
+    : argument).join(" ");
+}
+
+function commandProvenanceError(message = "Observed command evidence requires a ForgeLoop execution artifact") {
+  return artifactError("E_COMMAND_PROVENANCE_UNATTESTED", message, [ARTIFACT_PATHS.receipt]);
+}
+
+/**
+ * Revalidate the ForgeLoop-owned execution artifact behind an observed command
+ * check. This is intentionally asynchronous so completion and audit can verify
+ * the artifact instead of trusting duplicated check metadata.
+ */
+export async function validateCheckExecutionProvenance(check, {
+  target,
+  packageRoot,
+  taskId,
+  executionArtifacts,
+  allowForeignCwd = false,
+} = {}) {
+  if (check?.kind !== "command" || check.evidenceKind !== "OBSERVED") return null;
+  if (check.provenance !== "FORGELOOP_EXECUTED" || !check.executionRef) {
+    throw commandProvenanceError();
+  }
+  const artifact = executionArtifacts
+    ? { value: executionArtifacts[check.executionRef] }
+    : await readExecutionArtifact({
+      target,
+      executionRef: check.executionRef,
+      packageRoot,
+    });
+  if (!artifact.value) {
+    throw artifactError(
+      "E_EXECUTION_REF_INVALID",
+      "Execution reference does not resolve to an execution artifact in this bundle",
+      [ARTIFACT_PATHS.executionDirectory],
+    );
+  }
+  const execution = validateExecutionBinding({
+    execution: artifact.value,
+    taskId,
+    checkId: check.id,
+    requirement: check.requirement,
+    verificationCycle: check.details?.verificationCycle ?? 1,
+  });
+  if (!allowForeignCwd && path.resolve(execution.cwd) !== path.resolve(target)) {
+    throw artifactError(
+      "E_EXECUTION_REF_INVALID",
+      "Execution artifact cwd does not match the current target",
+      [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],
+    );
+  }
+  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],
+    );
+  }
+  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],
+    );
+  }
+  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,
+      });
+    }
+  }
+  return errors;
+}
+
 export async function requiredEvidenceForTarget({ target, contract, route, packageRoot, additionalEvidence = [] }) {
   const config = await readOptionalConfig(target, packageRoot);
   const guideEvidence = await completionEvidenceForGuides(route.value.guides, packageRoot);
@@ -196,42 +293,20 @@ function appendUniqueEvidence(evidence, nextEvidence) {
   return exists ? [...evidence] : [...evidence, nextEvidence];
 }
 
-export async function recordCheck({
+/**
+ * Read-only lifecycle checks shared by run-check and record-check. Keeping
+ * these checks before process launch prevents a command from running when the
+ * target is not ready to receive verification evidence.
+ */
+export async function assertRecordCheckPrerequisites({
   target,
   packageRoot,
-  id,
-  kind = "command",
   requirement,
   status,
   evidenceKind,
-  command,
-  result,
-  exitCode,
-  details,
   authorityContext,
   runtimeContext,
-}) {
-  requiredString(id, "check id");
-  requiredString(kind, "check kind");
-  requiredString(requirement, "check requirement");
-  requiredString(status, "check status");
-  requiredString(evidenceKind, "evidence kind");
-  if (command !== undefined && typeof command !== "string") {
-    throw artifactError("E_CHECK_INVALID", "command must be a string when supplied");
-  }
-  if (result !== undefined && typeof result !== "string") {
-    throw artifactError("E_CHECK_INVALID", "result must be a string when supplied");
-  }
-  if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
-    throw artifactError("E_CHECK_INVALID", "check details must be a JSON object");
-  }
-  if ((typeof command !== "string" || command.trim() === "")
-    && (typeof result !== "string" || result.trim() === "")) {
-    throw artifactError("E_CHECK_INVALID", "record-check requires --command or --result");
-  }
-
-  const commandSpec = typeof command === "string" && command.trim() !== "" ? command.trim() : undefined;
-
+} = {}) {
   const state = await readWorkState(target, packageRoot);
   if (!state) throw artifactError("E_STATE_MISSING", "Work state is required before recording a check", [ARTIFACT_PATHS.state]);
   if (["COMPLETE", "BLOCKED"].includes(state.phase)) {
@@ -274,9 +349,114 @@ export async function recordCheck({
     authorityContext,
     runtimeContext,
   });
-  const source = commandSpec || `check:${id}`;
-  const recordedResult = result?.trim() || `recorded command: ${commandSpec || source}`;
-  const classification = commandSpec !== undefined ? classifyCommandResolution(commandSpec) : null;
+  const ledger = await validateEventLedger(target, packageRoot);
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw artifactError(first.code, first.message, [ARTIFACT_PATHS.events]);
+  }
+  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],
+    );
+  }
+  return {
+    state,
+    contract,
+    route,
+    preflight,
+    requiredEvidence,
+    existingReceipt,
+    ledger,
+  };
+}
+
+export async function recordCheck({
+  target,
+  packageRoot,
+  id,
+  kind = "command",
+  requirement,
+  status,
+  evidenceKind,
+  command,
+  result,
+  exitCode,
+  details,
+  executionRef,
+  provenance,
+  authorityContext,
+  runtimeContext,
+}) {
+  requiredString(id, "check id");
+  requiredString(kind, "check kind");
+  requiredString(requirement, "check requirement");
+  requiredString(status, "check status");
+  requiredString(evidenceKind, "evidence kind");
+  if (command !== undefined && typeof command !== "string") {
+    throw artifactError("E_CHECK_INVALID", "command must be a string when supplied");
+  }
+  if (result !== undefined && typeof result !== "string") {
+    throw artifactError("E_CHECK_INVALID", "result must be a string when supplied");
+  }
+  if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
+    throw artifactError("E_CHECK_INVALID", "check details must be a JSON object");
+  }
+  if (executionRef !== undefined && (typeof executionRef !== "string" || executionRef.trim() === "")) {
+    throw artifactError("E_EXECUTION_REF_INVALID", "executionRef must be a non-empty string when supplied");
+  }
+  if (provenance !== undefined && !CHECK_PROVENANCE.includes(provenance)) {
+    throw artifactError("E_CHECK_INVALID", `provenance must be one of ${CHECK_PROVENANCE.join(", ")}`);
+  }
+  if ((typeof command !== "string" || command.trim() === "")
+    && (typeof result !== "string" || result.trim() === "")) {
+    throw artifactError("E_CHECK_INVALID", "record-check requires --command or --result");
+  }
+
+  const context = await assertRecordCheckPrerequisites({
+    target,
+    packageRoot,
+    requirement,
+    status,
+    evidenceKind,
+    authorityContext,
+    runtimeContext,
+  });
+  const {
+    state,
+    contract,
+    route,
+    requiredEvidence,
+    existingReceipt,
+  } = context;
+
+  const commandSpec = typeof command === "string" && command.trim() !== "" ? command.trim() : undefined;
+  const observedCommand = kind === "command" && evidenceKind === "OBSERVED";
+  if (observedCommand && (!executionRef || provenance !== "FORGELOOP_EXECUTED")) {
+    throw commandProvenanceError();
+  }
+  const execution = executionRef
+    ? await validateCheckExecutionProvenance({
+      kind,
+      evidenceKind,
+      provenance,
+      executionRef,
+      status,
+      exitCode,
+      id,
+      requirement,
+      details: { ...(details ?? {}), verificationCycle: state.verificationCycle ?? 1 },
+    }, {
+      target,
+      packageRoot,
+      taskId: contract.value.taskId,
+    })
+    : null;
+  const effectiveCommand = execution ? formatArgv(execution.argv) : commandSpec;
+  const source = effectiveCommand || `check:${id}`;
+  const recordedResult = result?.trim() || `recorded command: ${effectiveCommand || source}`;
+  const classification = execution?.resolution ?? (effectiveCommand !== undefined ? classifyCommandResolution(effectiveCommand) : null);
   const installationAuthorized = Boolean(
     details?.installationAuthorized
     || details?.authority?.softwareInstallation === "AUTHORIZED"
@@ -289,15 +469,28 @@ export async function recordCheck({
     status,
     evidenceKind,
     source,
+    ...(executionRef === undefined ? {} : { executionRef }),
+    ...(provenance === undefined ? {} : { provenance }),
     timestamp: new Date().toISOString(),
-    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(execution?.exitCode !== null && execution?.exitCode !== undefined
+      ? { exitCode: execution.exitCode }
+      : exitCode === undefined ? {} : { exitCode }),
     details: {
-      ...(command === undefined ? {} : { command }),
+      ...(effectiveCommand === undefined ? {} : { command: effectiveCommand }),
       ...(result === undefined ? {} : { result }),
       ...(details === undefined ? {} : details),
       verificationCycle: state.verificationCycle ?? 1,
       ...(classification ? {
         execution: {
+          ...(details?.execution ?? {}),
+          ...(execution ? {
+            executionRef: execution.executionId,
+            argv: [...execution.argv],
+            cwd: execution.cwd,
+            resolution: execution.resolution,
+            status: execution.status,
+            exitCode: execution.exitCode,
+          } : {}),
           resolutionMode: classification.resolutionMode,
           mayInstall: classification.mayInstall,
           installationAuthorized,
@@ -310,6 +503,7 @@ export async function recordCheck({
     packageRoot,
     authorityContext,
     runtimeContext,
+    requireCommandProvenance: observedCommand,
   });
   const evidence = createEvidence({
     kind: evidenceKind,
@@ -349,18 +543,6 @@ export async function recordCheck({
     authorityContext,
     runtimeContext,
   });
-  const ledger = await validateEventLedger(target, packageRoot);
-  if (!ledger.valid) {
-    const first = ledger.errors[0];
-    throw artifactError(first.code, first.message, [ARTIFACT_PATHS.events]);
-  }
-  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],
-    );
-  }
   const coverage = coverageForRequirements(requiredEvidence, checks, {
     target,
     taskId: contract.value.taskId,

package/src/core/completion.js

@@ -1,5 +1,5 @@
 import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { requiredEvidenceForTarget } from "./completion-artifacts.js";
+import { requiredEvidenceForTarget, validateChecksExecutionProvenance } from "./completion-artifacts.js";
 import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validateStateLedgerCoherence } from "./events.js";
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
@@ -42,6 +42,9 @@ function repairNext(error) {
     case "E_CHECK_INVALID":
     case "E_CHECK_STATUS_CONTRADICTION":
       return "Run forgeloop record-check with compatible observed evidence for the named requirement.";
+    case "E_COMMAND_PROVENANCE_UNATTESTED":
+    case "E_EXECUTION_REF_INVALID":
+      return "Run forgeloop run-check with the exact argv, or record the result as manual/NOT_VERIFIED evidence without claiming command execution.";
     case "E_EVIDENCE_PARTIAL":
       return "Run or finish the missing component checks and record observed evidence.";
     case "E_EVIDENCE_INVALID":
@@ -216,6 +219,21 @@ export async function evaluateCompletion({ target, packageRoot, strict = false,
     }
   }
 
+  if (contract) {
+    errors.push(...await validateChecksExecutionProvenance(state?.checks, {
+      target,
+      packageRoot,
+      taskId: contract.value.taskId,
+      artifactPath: ARTIFACT_PATHS.state,
+    }));
+    errors.push(...await validateChecksExecutionProvenance(receipt?.value?.checks, {
+      target,
+      packageRoot,
+      taskId: contract.value.taskId,
+      artifactPath: ARTIFACT_PATHS.receipt,
+    }));
+  }
+
   if (state && !["REVIEWING", "COMPLETE"].includes(state.phase)) {
     errors.push(issue("E_PHASE_PREREQUISITE_MISSING", `Completion requires REVIEWING or COMPLETE state, found ${state.phase}`, [ARTIFACT_PATHS.state]));
   }

package/src/core/conformance.js

@@ -1,6 +1,7 @@
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { createEvidence } from "./evidence.js";
 import { canonicalFingerprint } from "./artifacts.js";
+import { evaluateContinuityConformance } from "./continuity-conformance.js";
 
 function error(code, message, artifacts = []) {
   return { code, message, artifacts };
@@ -49,9 +50,13 @@ export function validateTaskArtifactSet({
   taskBriefs = [],
   delegatedResults = [],
   events = [],
+  continuity = null,
+  continuityContext = {},
 } = {}) {
   const errors = [];
   const incomplete = [];
+  const continuityResult = evaluateContinuityConformance({ continuity, state, ...continuityContext });
+  errors.push(...continuityResult.errors);
 
   addVersionErrors(route, "route", errors);
   addVersionErrors(state, "state", errors);
@@ -122,11 +127,11 @@ export function validateTaskArtifactSet({
 
   const sortedErrors = sortErrors(errors);
   let status = "VALID";
-  if (sortedErrors.some((item) => item.code === "UNSUPPORTED_PROTOCOL_VERSION")) {
+  if (sortedErrors.some((item) => item.code === "UNSUPPORTED_PROTOCOL_VERSION") || continuityResult.status === "INVALID") {
     status = "INVALID";
   } else if (sortedErrors.length > 0) {
     status = "INCONSISTENT";
-  } else if (stateClassification?.status === "REVALIDATION_REQUIRED") {
+  } else if (stateClassification?.status === "REVALIDATION_REQUIRED" || continuityResult.status === "STALE") {
     status = "STALE";
   } else if (incomplete.length > 0) {
     status = "INCOMPLETE";
@@ -173,6 +178,7 @@ export function validateTaskArtifactSet({
     incomplete: [...new Set(incomplete)].sort(),
     stale,
     delegation,
+    continuity: continuityResult,
     evidence: [createEvidence({
       kind: evidenceKind,
       source: "ForgeLoop protocol conformance",

package/src/core/continuity-cli-options.js

@@ -0,0 +1,58 @@
+const OPTION_FIELDS = Object.freeze({
+  "--focus-id": ["continuityFocusId", false],
+  "--focus-summary": ["continuityFocusSummary", false],
+  "--remaining": ["continuityRemaining", true],
+  "--known-issue": ["continuityKnownIssues", true],
+  "--changed-area": ["continuityChangedAreas", true],
+  "--inspect-first": ["continuityInspectFirst", true],
+  "--resume-note": ["continuityResumeNote", false],
+});
+
+export function continuityOptionDefaults() {
+  return {
+    continuityFocusId: null,
+    continuityFocusSummary: null,
+    continuityRemaining: [],
+    continuityKnownIssues: [],
+    continuityChangedAreas: [],
+    continuityInspectFirst: [],
+    continuityResumeNote: null,
+  };
+}
+
+export function consumeContinuityOption({ argument, argv, index, options }) {
+  const definition = OPTION_FIELDS[argument];
+  if (!definition) return { handled: false, index };
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) throw new Error(`${argument} requires a value`);
+  const [field, repeatable] = definition;
+  if (repeatable) options[field].push(value);
+  else options[field] = value;
+  return { handled: true, index: index + 1 };
+}
+
+export function hasContinuityOptions(options = {}) {
+  return Boolean(
+    options.continuityFocusId
+    || options.continuityFocusSummary
+    || options.continuityResumeNote
+    || options.continuityRemaining?.length
+    || options.continuityKnownIssues?.length
+    || options.continuityChangedAreas?.length
+    || options.continuityInspectFirst?.length
+  );
+}
+
+export function validateContinuityOptions(command, options = {}) {
+  if (command !== "record-continuity" && hasContinuityOptions(options)) {
+    throw new Error(`Continuity recording options are not valid for ${command}`);
+  }
+  if (command === "record-continuity") {
+    const hasFocusId = Boolean(options.continuityFocusId);
+    const hasFocusSummary = Boolean(options.continuityFocusSummary);
+    if (hasFocusId !== hasFocusSummary) {
+      throw new Error("record-continuity requires --focus-id and --focus-summary together");
+    }
+  }
+  return options;
+}

package/src/core/continuity-conformance.js

@@ -0,0 +1,46 @@
+import { classifyContinuity } from "./continuity-reconciliation.js";
+
+function error(code, message) {
+  return { code, message, artifacts: ["continuity", "state"] };
+}
+
+export function evaluateContinuityConformance(input = {}) {
+  if (!input.continuity) {
+    return {
+      required: false,
+      status: "NOT_APPLICABLE",
+      classification: "ABSENT",
+      errors: [],
+      reasonCodes: [],
+      reasons: ["CONTINUITY_ABSENT"],
+      authority: "OPERATIONAL_CONTEXT_ONLY",
+      evidenceAuthority: "NONE",
+    };
+  }
+
+  const classification = classifyContinuity(input);
+  const result = {
+    required: false,
+    status: classification.classification === "FRESH"
+      ? "VALID"
+      : classification.classification === "RECONCILIATION_REQUIRED"
+        ? "STALE"
+        : classification.classification === "NOT_APPLICABLE"
+          ? "NOT_APPLICABLE"
+          : classification.classification,
+    classification: classification.classification,
+    errors: [],
+    reasonCodes: [...classification.reasonCodes],
+    reasons: [...classification.reasons],
+    authority: "OPERATIONAL_CONTEXT_ONLY",
+    evidenceAuthority: "NONE",
+  };
+
+  if (["INVALID", "INCONSISTENT"].includes(classification.classification)) {
+    result.errors = classification.reasonCodes.map((code, index) => error(
+      code,
+      classification.reasons[index] ?? `Continuity is ${classification.classification.toLowerCase()}`,
+    ));
+  }
+  return result;
+}

package/src/core/continuity-observability.js

@@ -0,0 +1,20 @@
+const HEALTHY = new Set(["ABSENT", "FRESH", "NOT_APPLICABLE"]);
+
+export function continuityIsHealthy(result) {
+  return HEALTHY.has(result?.classification ?? "ABSENT");
+}
+
+export function continuityFinding(result) {
+  if (continuityIsHealthy(result)) return null;
+  const classification = result?.classification ?? "INVALID";
+  const severity = classification === "RECONCILIATION_REQUIRED" ? "warning" : "error";
+  return {
+    code: `continuity-${classification.toLowerCase().replaceAll("_", "-")}`,
+    severity,
+    path: result?.path ?? ".forgeloop/continuity.json",
+    message: result?.reasons?.join(", ") || `Continuity is ${classification}`,
+    remediation: classification === "RECONCILIATION_REQUIRED"
+      ? "Run forgeloop reconcile-continuity, inspect the current checkout, then record corrected continuity before advancing verification."
+      : "Repair or clear continuity after reviewing the current work state and checkout.",
+  };
+}