@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/core/preflight-consistency.js

@@ -80,6 +80,18 @@ function sameReadyPreflightEvent(event, result) {
     && sameStringSet(event.details?.satisfiedGates, result.satisfiedGates);
 }
 
+function latestContractRevisionSeq(events) {
+  return events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+}
+
+function hasCurrentRevisionGate(events, taskId, gate) {
+  const revisionSeq = latestContractRevisionSeq(events);
+  return events.some((event) => event.event === "GATE_SATISFIED"
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > revisionSeq);
+}
+
 export async function validateReadyProtocolConsistency({
   target,
   packageRoot,
@@ -141,9 +153,7 @@ export async function validateReadyProtocolConsistency({
     }
   }
   for (const gate of persisted.satisfiedGates ?? []) {
-    if (!events.some((event) => event.event === "GATE_SATISFIED"
-      && event.taskId === persisted.taskId
-      && event.details?.gate === gate)) {
+    if (!hasCurrentRevisionGate(events, persisted.taskId, gate)) {
       errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
     }
   }
@@ -189,9 +199,12 @@ export function assertExistingReadyLifecycleCompatibility(ledger, result) {
   const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
   if (!existingReady) return;
   const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
+  const revisedAfterReady = events.some((event) => event.event === "CONTRACT_REVISED"
+    && event.taskId === result.taskId
+    && event.seq > existingReady.seq);
   // A READY outcome superseded by a later BLOCKED outcome may be replaced by a
   // fresh READY with different details once the blocked preflight is resolved.
-  if (latestOutcome?.event === "PREFLIGHT_BLOCKED") return;
+  if (latestOutcome?.event === "PREFLIGHT_BLOCKED" || revisedAfterReady) return;
   if (!sameReadyPreflightEvent(existingReady, result)) {
     throw preflightError(
       "E_PHASE_CHRONOLOGY_INVALID",
@@ -217,9 +230,7 @@ export async function appendActivationEvents(target, packageRoot, ledger, result
     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)) {
+    if (!hasCurrentRevisionGate(events, result.taskId, gate)) {
       await append({ taskId: result.taskId, event: "GATE_SATISFIED", details: { gate } });
     }
   }
@@ -227,15 +238,18 @@ export async function appendActivationEvents(target, packageRoot, ledger, result
   const existingReady = events.findLast((event) => event.event === "PREFLIGHT_READY" && event.taskId === result.taskId);
   const latestOutcome = latestPreflightOutcomeEvent(events, result.taskId);
   const readySupersededByBlocked = existingReady && latestOutcome?.event === "PREFLIGHT_BLOCKED";
+  const readySupersededByContractRevision = existingReady && events.some((event) => event.event === "CONTRACT_REVISED"
+    && event.taskId === result.taskId
+    && event.seq > existingReady.seq);
   if (result.status === "READY") {
-    if (existingReady && !readySupersededByBlocked && !sameReadyPreflightEvent(existingReady, result)) {
+    if (existingReady && !readySupersededByBlocked && !readySupersededByContractRevision && !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 || readySupersededByBlocked) {
+    if (!existingReady || readySupersededByBlocked || readySupersededByContractRevision) {
       await append({
         taskId: result.taskId,
         event: "PREFLIGHT_READY",

package/src/core/preflight-loaders.js

@@ -2,13 +2,15 @@ import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
 import { readContract } from "./contract.js";
 import { readGateIfPresent, validateGateArtifacts } from "./gate-artifact.js";
 import { requiredGatesForGuides } from "./guide-metadata.js";
-import { assertSourceProvenance } from "./sources.js";
+import { assertContractPresetRefs, assertContractSourceProvenance, externalContractSourceRefs } from "./sources.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { ensureWithin, readBytes } from "./filesystem.js";
 import { sha256 } from "./manifest.js";
 import { findProfilePath } from "./profile.js";
 import { issue } from "./preflight-model.js";
 import { taskGatePath, taskArtifactPath } from "./task-paths.js";
+import { readEvents } from "./events.js";
+import { hasCurrentGateEvidence } from "./gate-provenance.js";
 
 export async function readProfile(target) {
   const relativePath = await findProfilePath(target);
@@ -62,15 +64,25 @@ export async function loadRoute(target, packageRoot, errors, options = {}) {
 
 export async function loadSources(target, contract, packageRoot, errors) {
   if (!contract?.value?.sourceRefs?.length) return null;
-  let registry;
+  const refs = contract.value.sourceRefs;
   try {
-    registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+    assertContractPresetRefs(refs);
   } catch (error) {
-    errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_PROFILE_SOURCE_MISSING" : "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+    errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
     return null;
   }
+  const externalRefs = externalContractSourceRefs(refs);
+  let registry;
+  if (externalRefs.length > 0) {
+    try {
+      registry = (await readJsonArtifact(target, ARTIFACT_PATHS.sources, "source-registry", packageRoot)).value;
+    } catch (error) {
+      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_PROFILE_SOURCE_MISSING" : "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
+      return null;
+    }
+  }
   try {
-    assertSourceProvenance(registry, contract.value.sourceRefs);
+    assertContractSourceProvenance(registry, refs);
   } catch (error) {
     errors.push(issue(error.code ?? "E_PROFILE_SOURCE_UNKNOWN", error.message, [ARTIFACT_PATHS.sources]));
   }
@@ -84,6 +96,15 @@ export async function inspectGates(target, contract, route, packageRoot, errors,
   const satisfied = [];
   const records = {};
   const taskId = options.taskId ?? null;
+  let events = [];
+  if (taskId) {
+    try {
+      events = await readEvents(target, packageRoot, { taskId });
+    } catch {
+      events = [];
+    }
+  }
+  const latestContractRevisionSeq = events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
   for (const gate of required) {
     let artifact;
     const defaultGateRel = taskId ? taskGatePath(taskId, gate) : `${ARTIFACT_PATHS.gates}/${gate}.json`;
@@ -111,6 +132,17 @@ export async function inspectGates(target, contract, route, packageRoot, errors,
       errors.push(issue("E_GATE_STALE", `Gate ${gate} references stale artifacts`, [artifact.path], { gate, stale }));
       continue;
     }
+    const currentEpochSatisfied = latestContractRevisionSeq === 0
+      || hasCurrentGateEvidence(events, taskId, gate, latestContractRevisionSeq);
+    if (!currentEpochSatisfied) {
+      errors.push(issue(
+        "E_GATE_UNVERIFIED",
+        `Required gate ${gate} was satisfied before the current contract revision`,
+        [defaultGateRel],
+        { gate },
+      ));
+      continue;
+    }
     satisfied.push(gate);
   }
   return { required, satisfied: satisfied.sort(), records };

package/src/core/protocol-info.js

@@ -4,6 +4,8 @@ import { PUBLIC_ERROR_REGISTRY } from "./error-codes.js";
 import { GUIDE_REGISTRY } from "./guide-registry.js";
 import { PROTOCOL_VERSION, WORK_PHASES, WORK_TRANSITIONS } from "./protocol.js";
 import { VERIFICATION_ISOLATION_MODES } from "./verification-execution.js";
+import { PROVIDER_KINDS } from "../providers/capabilities.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "./decision/constants.js";
 
 export const SCHEMA_COMPATIBILITY_POLICY = Object.freeze({
   protocolVersion: PROTOCOL_VERSION,
@@ -36,6 +38,42 @@ export function protocolInfo({ packageVersion = null } = {}) {
     writesSchemaVersions: schemaVersions,
     compatibility: SCHEMA_COMPATIBILITY_POLICY,
     features: {
+      semanticDecisionPlane: {
+        version: 1,
+        supported: true,
+        requiredForNewSemanticDecisions: true,
+        engine: DECISION_ENGINE_ID,
+        model: PINNED_JEV_MODEL,
+        policyVersion: DECISION_DEFAULT_POLICY.policyVersion,
+        authority: "SEMANTIC_DECISION",
+        evidenceAuthority: "NONE",
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        ownershipAuthority: false,
+        installationAuthority: false,
+        commands: ["decision-status", "decision-show", "context-plan", "model-route", "semantic-plan", "test-inventory", "test-utility", "test-prune-plan", "test-prune-probe"],
+        resource: "task/decisions",
+        contextPlanResource: "task/context-plan",
+        modelRouteResource: "task/model-route",
+        testUtilityResource: "task/test-utility",
+        testPruneResource: "task/test-utility",
+        offlineInspection: true,
+        completePerformsLiveRequest: false,
+        modelRouting: {
+          version: 1,
+          tiers: ["NONE", "FAST", "STANDARD", "PRIMARY"],
+          deterministicFloor: true,
+          advisoryEscalationOnly: true,
+          vendorSelection: false,
+        },
+        semanticPlanning: {
+          version: 1,
+          questionSets: ["intake-v1", "contract-v1", "route-v1", "context-v1", "model-route-v1", "failure-v1", "diagnosis-v1", "review-v1", "task-overlap-v1", "test-utility-v1", "test-prune-v1"],
+          authority: "SEMANTIC_DECISION",
+          evidenceAuthority: "NONE",
+          lifecycleAuthority: false,
+        },
+      },
       taskClaimRecovery: {
         version: 1,
         durableRecoveryState: true,
@@ -153,6 +191,18 @@ export function protocolInfo({ packageVersion = null } = {}) {
         commands: ["next", "task-show"],
         preservesDefaultOutput: true,
       },
+      auditUx: {
+        version: 1,
+        supported: true,
+        readOnly: true,
+        resource: "task/audit-view",
+        timeline: true,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        completionAuthority: false,
+        mutationAuthority: false,
+        externalExecution: false,
+      },
       usageTelemetry: {
         version: 1,
         supported: true,
@@ -205,6 +255,21 @@ export function protocolInfo({ packageVersion = null } = {}) {
         evidenceAuthority: false,
         executable: false,
       },
+      providerExtensions: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        maturity: "experimental",
+        publicRegistryApi: false,
+        packageSubpathExported: false,
+        autoInstall: false,
+        lifecycleAuthority: false,
+        completionAuthority: false,
+        evidenceAuthority: false,
+        providerKinds: [...PROVIDER_KINDS],
+        resultBoundary: "STRICT_JSON_SNAPSHOT",
+        cancellation: "COOPERATIVE_ABORT_SIGNAL",
+      },
       responsibilityConstraints: {
         version: 1,
         supported: true,

package/src/core/protocol.js

@@ -30,6 +30,9 @@ export const FAILURE_CODES = Object.freeze([
   "E_GATE_REQUIRED",
   "E_GATE_UNVERIFIED",
   "E_GATE_STALE",
+  "E_GATE_NOT_REQUIRED",
+  "E_GATE_INVALID",
+  "E_PHASE_FREEZE",
   "E_PHASE_TRANSITION_INVALID",
   "E_PHASE_PREREQUISITE_MISSING",
   "E_PHASE_CHRONOLOGY_INVALID",
@@ -113,6 +116,23 @@ export const FAILURE_CODES = Object.freeze([
   "E_INTERVENTION_HYPOTHESIS_MISSING",
   "E_INTERVENTION_REFERENCE_INVALID",
   "E_STRATEGY_OSCILLATION",
+  "E_DECISION_ENGINE_UNAVAILABLE",
+  "E_DECISION_ENGINE_AUTH_REQUIRED",
+  "E_DECISION_ENGINE_AUTH_INVALID",
+  "E_DECISION_MODEL_UNSUPPORTED",
+  "E_DECISION_REQUEST_INVALID",
+  "E_DECISION_RESULT_INVALID",
+  "E_DECISION_TIMEOUT",
+  "E_DECISION_RATE_LIMITED",
+  "E_DECISION_STATE_UNSAFE",
+  "E_DECISION_STATE_LIMIT",
+  "E_DECISION_LOW_CONFIDENCE",
+  "E_DECISION_STALE",
+  "E_DECISION_POLICY_INVALID",
+  "E_DECISION_CACHE_INVALID",
+  "E_DECISION_QUESTION_SET_UNKNOWN",
+  "E_DECISION_QUESTION_SET_STALE",
+  "E_DECISION_REQUIRED",
   "E_DECISION_CRITERION_INVALID",
   "E_DECISION_NOT_UNRESOLVED",
 ]);

package/src/core/reconcile-closure.js

@@ -1,18 +1,17 @@
 import { readContract } from "./contract.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateEventLedger } from "./events.js";
 import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebind.js";
 import { runCommandExecution } from "./execution.js";
 import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
 import { taskArtifactPath } from "./task-paths.js";
+import { resolveTaskClaimState } from "./task-claim-state.js";
 import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 import { classifyRequirement } from "./evidence-readiness.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
-const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
-
 const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
 
 function reconcileError(code, message, artifacts = []) {
@@ -22,14 +21,126 @@ function reconcileError(code, message, artifacts = []) {
   return error;
 }
 
+function assertRepositoryOnlyFreshness(freshness, stateRel, contractRel) {
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    throw reconcileError(
+      "E_RECONCILE_NOT_STALE",
+      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
+      [stateRel, contractRel],
+    );
+  }
+  if (freshness.reasons.length === 1 && freshness.reasons[0] === "REPOSITORY_CHANGED") return;
+  throw reconcileError(
+    "E_RECONCILE_UNSUPPORTED_DRIFT",
+    `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${freshness.reasons.join(", ")}`,
+    [stateRel, contractRel],
+  );
+}
+
+async function assertFreshReviewingRecoveryIsAuthorized({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  eventsRel,
+  receiptRel,
+}) {
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) return;
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) return;
+  let receipt = null;
+  try {
+    receipt = (await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot)).value;
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  const recoveryAuth = validateCompletionRecoveryAuthorization({ state, receipt, events: ledger.events });
+  if (!recoveryAuth.authorized) {
+    const first = recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [eventsRel, receiptRel],
+    );
+  }
+}
+
+async function validateReconciliationCheckpoint({
+  target,
+  packageRoot,
+  taskId,
+  state,
+  stateRel,
+  contractRel,
+  eventsRel,
+  receiptRel,
+  authorityContext,
+  runtimeContext,
+}) {
+  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
+  if (freshness.status !== "REVALIDATION_REQUIRED") {
+    await assertFreshReviewingRecoveryIsAuthorized({
+      target,
+      packageRoot,
+      taskId,
+      state,
+      eventsRel,
+      receiptRel,
+    });
+  }
+  assertRepositoryOnlyFreshness(freshness, stateRel, contractRel);
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const first = ledger.errors[0];
+    throw reconcileError(
+      "E_RECONCILE_LEDGER_INVALID",
+      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
+      [eventsRel],
+    );
+  }
+
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed || ownership.claimState !== "ACTIVE") {
+    const first = ownership.ownershipErrors?.[0] ?? ownership.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+      `reconcile-closure requires active, valid task claim ownership: ${first.message ?? ownership.claimState}`,
+      [stateRel, eventsRel],
+    );
+  }
+
+  if (state.phase !== "REVIEWING" || !Object.prototype.hasOwnProperty.call(state, "lastCompletionAttempt")) {
+    return state;
+  }
+
+  const recovery = await authorizeCompletionRecoveryOrRebind({
+    target,
+    packageRoot,
+    taskId,
+    authorityContext,
+    runtimeContext,
+  });
+  if (!recovery.recoveryAuth.authorized) {
+    const first = recovery.recoveryAuth.errors?.[0] ?? {};
+    throw reconcileError(
+      first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+      `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+      [stateRel, receiptRel],
+    );
+  }
+  return recovery.rebound ? recovery.state : state;
+}
+
 /**
  * Canonical recovery for an EXECUTING, VERIFYING, or REVIEWING task whose
  * objective is already satisfied in the current repository but whose
  * work-state checkpoint is stale because the repository fingerprint moved.
  *
  * The command refreshes the checkpoint repository fingerprint only after:
- *   - the task is EXECUTING, VERIFYING, or (with authorized completion
- *     recovery) REVIEWING,
+ *   - the task is EXECUTING, VERIFYING, or REVIEWING (with either a
+ *     persisted completion rejection or the narrow repository-only bootstrap
+ *     path),
  *   - classification requires revalidation and the only drift is
  *     REPOSITORY_CHANGED,
  *   - the append-only event ledger is valid,
@@ -81,53 +192,18 @@ export async function runReconcileClosure({
       [stateRel],
     );
   }
-  if (state.phase === "REVIEWING") {
-    const recovery = await authorizeCompletionRecoveryOrRebind({
-      target,
-      packageRoot,
-      taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    if (!recovery.recoveryAuth.authorized) {
-      const first = recovery.recoveryAuth.errors?.[0] ?? {};
-      throw reconcileError(
-        first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
-        `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
-        [stateRel, receiptRel],
-      );
-    }
-    if (recovery.rebound) {
-      state = recovery.state;
-    }
-  }
-
-  const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
-  if (freshness.status !== "REVALIDATION_REQUIRED" || !freshness.reasons.includes("REPOSITORY_CHANGED")) {
-    throw reconcileError(
-      "E_RECONCILE_NOT_STALE",
-      `work-state checkpoint is ${freshness.status === "FRESH" ? "fresh" : "not revalidation-required"}; no reconciliation required`,
-      [stateRel, contractRel],
-    );
-  }
-  const unsupported = freshness.reasons.filter((reason) => !RECONCILABLE_DRIFT.has(reason));
-  if (unsupported.length > 0) {
-    throw reconcileError(
-      "E_RECONCILE_UNSUPPORTED_DRIFT",
-      `reconcile-closure only reconciles repository fingerprint drift; unresolved drift: ${unsupported.join(", ")}`,
-      [stateRel, contractRel],
-    );
-  }
-
-  const ledger = await validateEventLedger(target, packageRoot, { taskId });
-  if (!ledger.valid) {
-    const first = ledger.errors[0];
-    throw reconcileError(
-      "E_RECONCILE_LEDGER_INVALID",
-      `append-only event ledger must be valid before reconciliation: ${first?.message ?? "invalid ledger"}`,
-      [eventsRel],
-    );
-  }
+  state = await validateReconciliationCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    stateRel,
+    contractRel,
+    eventsRel,
+    receiptRel,
+    authorityContext,
+    runtimeContext,
+  });
 
   const contract = await readContract(target, packageRoot, { taskId });
   const verificationItem = (contract.value.verification ?? []).find((item) => {

package/src/core/recovery-history.js

@@ -6,6 +6,7 @@ import {
 const RECOVERY_EVENT_TYPES = new Set([
   "TASK_RECOVERY_RECORDED",
   "OPERATOR_RECOVERY_RECORDED",
+  "TASK_ABANDONED",
   LEGACY_RECOVERY_MIGRATION_EVENT,
 ]);