@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/src/commands/task-migrate-contract-bootstrap-repair.js

@@ -0,0 +1,288 @@
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import {
+  classifyLockStaleness,
+  readLockInfo,
+  releaseStaleTaskLockIfUnchanged,
+  withProjectClaimsLock,
+} from "../core/task-lock.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { readWorkState } from "../core/work-state.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_DEFECT,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT,
+  CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_VERSION,
+  assertContractBootstrapRepairMigrationDetails,
+  isLegacyContractBootstrapRepairMigrationCandidate,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
+import {
+  E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AUTHORIZATION_REQUIRED,
+  E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+  E_TASK_LOCKED,
+} from "../core/error-codes.js";
+
+function migrationError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function routePath(taskId) {
+  return taskArtifactPath(taskId, "route");
+}
+
+async function proveLegacyRepairState(target, packageRoot, taskId, marker) {
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (contract.fingerprint !== marker.details.contractFingerprint) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current contract does not match the legacy repair marker fingerprint",
+      { artifacts: [taskArtifactPath(taskId, "contract")] },
+    );
+  }
+
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (!state) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state is required to prove the legacy repair boundary",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+  if (state.taskId !== taskId
+    || state.phase !== marker.details.reconstructedPhase
+    || state.contractFingerprint !== marker.details.contractFingerprint
+    || canonicalFingerprint(state) !== marker.details.reconstructedStateFingerprint) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state does not exactly match the legacy repair marker reconstruction",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+  if (!Number.isInteger(state.revision) || state.revision < 0) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current work-state revision is not a valid non-negative integer",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+
+  let route = null;
+  if (state.phase === "ROUTED") {
+    try {
+      route = await readPersistedRoute(target, packageRoot, { taskId });
+    } catch (error) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        `ROUTED legacy repair requires a readable persisted route: ${error.message}`,
+        { artifacts: [routePath(taskId)] },
+      );
+    }
+    if (marker.details.routeFingerprint === null
+      || state.routeFingerprint !== marker.details.routeFingerprint
+      || route.fingerprint !== marker.details.routeFingerprint
+      || route.value.contractFingerprint !== marker.details.contractFingerprint) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        "Persisted route does not exactly match the legacy repair marker reconstruction",
+        { artifacts: [routePath(taskId)] },
+      );
+    }
+  } else if (marker.details.routeFingerprint !== null || state.routeFingerprint !== undefined) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "CONTRACT_READY legacy repair must not claim a route",
+      { artifacts: [taskArtifactPath(taskId, "state")] },
+    );
+  }
+
+  return { contract, state, route };
+}
+
+function migrationResult(taskId, candidate, migrationEvent, alreadyMigrated) {
+  return {
+    taskId,
+    migrated: !alreadyMigrated,
+    alreadyMigrated,
+    legacyMarkerSeq: candidate.marker.seq,
+    legacyRepairCommitSeq: candidate.repairCommit.seq,
+    migrationEventSeq: migrationEvent?.seq ?? null,
+    repairId: candidate.marker.details.repairId,
+    reconstructedPhase: candidate.marker.details.reconstructedPhase,
+  };
+}
+
+async function inspectAlreadyMigrated(target, packageRoot, taskId, ledger) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (!ledger.valid || !anchor || anchor.kind !== "MIGRATED_LEGACY") {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Existing contract bootstrap migration is invalid or the ledger is not strict",
+    );
+  }
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Current task state no longer satisfies the migrated task ownership invariants",
+      { errors: ownership.errors },
+    );
+  }
+  return migrationResult(taskId, { marker: anchor.sourceMarker, repairCommit: ledger.events[anchor.sourceMarker.seq] }, anchor.migrationEvent, true);
+}
+
+export async function runTaskMigrateContractBootstrapRepair({ target, packageRoot, taskId, acknowledgeMigration } = {}) {
+  if (!acknowledgeMigration) {
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AUTHORIZATION_REQUIRED,
+      "task-migrate-contract-bootstrap-repair requires fresh explicit --acknowledge-migration",
+    );
+  }
+
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await validateEventLedger(target, packageRoot, {
+    taskId: effectiveTaskId,
+    allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+  });
+  if (!initial.valid) {
+    const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Ledger is not structurally trustworthy for legacy contract bootstrap migration",
+      { errors: initial.errors },
+    );
+  }
+  const initialCandidate = isLegacyContractBootstrapRepairMigrationCandidate(initial.events, effectiveTaskId);
+  if (!initialCandidate) {
+    const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+    throw migrationError(
+      E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+      "Ledger does not match the exact legacy contract bootstrap repair migration boundary",
+      { errors: initial.errors },
+    );
+  }
+
+  return withProjectClaimsLock(target, "task-migrate-contract-bootstrap-repair", async () => {
+    const lock = await readLockInfo(target, effectiveTaskId);
+    const status = classifyLockStaleness(lock);
+    if (status.status === "LIVE") throw migrationError(E_TASK_LOCKED, `Task ${effectiveTaskId} has a live mutation lock`);
+    if (status.status === "UNKNOWN" || status.status === "CORRUPT") {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        `Task ${effectiveTaskId} lock state is ${status.status}; refusing unsafe migration`,
+      );
+    }
+    if (status.status === "STALE") {
+      const released = await releaseStaleTaskLockIfUnchanged(target, effectiveTaskId, lock);
+      if (!released.released && released.reason !== "LOCK_MISSING") {
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          `Task ${effectiveTaskId} stale lock could not be safely released: ${released.reason}`,
+        );
+      }
+    }
+
+    const result = await withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-migrate-contract-bootstrap-repair",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async () => {
+      const locked = await validateEventLedger(target, packageRoot, {
+        taskId: effectiveTaskId,
+        allowUnmigratedLegacyContractBootstrapRepairMarkers: true,
+      });
+      if (!locked.valid) {
+        const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+        if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Pre-commit ledger revalidation failed inside the migration transaction",
+          { errors: locked.errors },
+        );
+      }
+      const candidate = isLegacyContractBootstrapRepairMigrationCandidate(locked.events, effectiveTaskId);
+      if (!candidate
+        || candidate.marker.seq !== initialCandidate.marker.seq
+        || candidate.marker.hash !== initialCandidate.marker.hash
+        || candidate.repairCommit.hash !== initialCandidate.repairCommit.hash) {
+        const strict = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+        if (strict.valid) return inspectAlreadyMigrated(target, packageRoot, effectiveTaskId, strict);
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Ledger changed between inspection and migration lock; aborting",
+        );
+      }
+
+      const proof = await proveLegacyRepairState(target, packageRoot, effectiveTaskId, candidate.marker);
+      const coherenceErrors = validateStateLedgerCoherence(proof.state, locked.events);
+      if (coherenceErrors.length > 0) {
+        throw migrationError(
+          E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+          "Work-state and ledger are not coherent at the legacy repair boundary",
+          { errors: coherenceErrors },
+        );
+      }
+      const migratedAt = new Date().toISOString();
+      const details = {
+        migrationVersion: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_VERSION,
+        defect: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_DEFECT,
+        legacyMarkerSeq: candidate.marker.seq,
+        legacyMarkerHash: candidate.marker.hash,
+        legacyRepairId: candidate.marker.details.repairId,
+        legacyRepairCommitSeq: candidate.repairCommit.seq,
+        legacyRepairCommitHash: candidate.repairCommit.hash,
+        legacyRepairTransactionId: candidate.repairCommit.details.transactionId,
+        taskId: effectiveTaskId,
+        contractFingerprint: candidate.marker.details.contractFingerprint,
+        reconstructedPhase: candidate.marker.details.reconstructedPhase,
+        routeFingerprint: candidate.marker.details.routeFingerprint,
+        reconstructedStateFingerprint: candidate.marker.details.reconstructedStateFingerprint,
+        reconstructedStateRevision: proof.state.revision,
+        migratedAt,
+        authorityKind: CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+      };
+      assertContractBootstrapRepairMigrationDetails(details);
+      const migrationEvent = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_EVENT,
+        at: migratedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+      return migrationResult(effectiveTaskId, candidate, migrationEvent, false);
+    });
+
+    const finalLedger = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+    if (!finalLedger.valid) {
+      throw migrationError(
+        E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID,
+        "Post-migration ledger validation failed; the legacy repair remains unverified",
+        { errors: finalLedger.errors },
+      );
+    }
+    return result;
+  });
+}
+
+export function formatTaskMigrateContractBootstrapRepairResult(result) {
+  return [
+    `taskId: ${result.taskId}`,
+    `migration: ${result.alreadyMigrated ? "already migrated" : "migrated"}`,
+    `legacy marker seq: ${result.legacyMarkerSeq}`,
+    `migration event seq: ${result.migrationEventSeq}`,
+    `repairId: ${result.repairId}`,
+    "",
+  ].join("\n");
+}

package/src/commands/task-repair-contract-bootstrap.js

@@ -0,0 +1,263 @@
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger } from "../core/events.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { withProjectClaimsLock, readLockInfo, classifyLockStaleness, releaseStaleTaskLockIfUnchanged } from "../core/task-lock.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { createWorkState, mutateWorkState, readWorkState } from "../core/work-state.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+  CONTRACT_BOOTSTRAP_REPAIR_DEFECT,
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  CONTRACT_BOOTSTRAP_REPAIR_VERSION,
+  assertContractBootstrapRepairDetails,
+  contractBootstrapRepairId,
+  isContractBootstrapRepairCandidate,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
+import {
+  E_CONTRACT_BOOTSTRAP_REPAIR_AUTHORIZATION_REQUIRED,
+  E_CONTRACT_BOOTSTRAP_REPAIR_INVALID,
+  E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE,
+  E_TASK_LOCKED,
+} from "../core/error-codes.js";
+
+function repairError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+async function readRouteIfProven(target, packageRoot, taskId, events, contractFingerprint) {
+  const routePath = taskArtifactPath(taskId, "route");
+  const hasRouteValidated = events.some((event) => event.event === "ROUTE_VALIDATED");
+  if (!hasRouteValidated) return null;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId });
+    if (route.value.contractFingerprint !== contractFingerprint) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Persisted route does not bind to the canonical contract fingerprint");
+    }
+    return route;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "ROUTE_VALIDATED history requires a persisted route artifact", { artifacts: [routePath] });
+    }
+    if (error.code === E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE) throw error;
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Persisted route cannot be proven safe: ${error.message}`, { artifacts: [routePath] });
+  }
+}
+
+function stateForRepair(state, { taskId, contractFingerprint, route, repository }) {
+  const routed = Boolean(route);
+  const phase = routed ? "ROUTED" : "CONTRACT_READY";
+  const steps = routed
+    ? { completedSteps: ["contract", "route"], pendingSteps: ["planning", "implementation", "verification"] }
+    : { completedSteps: ["contract"], pendingSteps: ["route", "planning", "implementation", "verification"] };
+  const base = state ? {
+    ...state,
+    taskId,
+    contractFingerprint,
+    ...(routed ? { routeFingerprint: route.fingerprint } : { routeFingerprint: undefined }),
+    repositoryFingerprint: repository,
+    phase,
+    selectedGuides: routed ? [...route.value.guides] : [],
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
+    revision: (state.revision ?? 0) + 1,
+    lastUpdated: new Date().toISOString(),
+    ...(state.phase !== phase ? { previousPhase: state.phase } : {}),
+  } : createWorkState({
+    taskId,
+    contractFingerprint,
+    ...(routed ? { routeFingerprint: route.fingerprint } : {}),
+    repositoryFingerprint: repository,
+    phase,
+    selectedGuides: routed ? [...route.value.guides] : [],
+    requiredGates: [],
+    satisfiedGates: [],
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+    revision: 0,
+  });
+  if (base.routeFingerprint === undefined) delete base.routeFingerprint;
+  return createWorkState(base);
+}
+
+function assertStateCompatible(state, taskId, contractFingerprint, route) {
+  if (!state) return;
+  if (state.taskId !== taskId || state.contractFingerprint !== contractFingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state is bound to a different task or contract");
+  }
+  if (!["CONTRACT_READY", "ROUTED"].includes(state.phase)) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Existing work-state phase ${state.phase} is beyond the repair boundary`);
+  }
+  if (route && state.routeFingerprint !== undefined && state.routeFingerprint !== route.fingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state route fingerprint conflicts with the proven route");
+  }
+  if (!route && state.routeFingerprint !== undefined) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state claims a route that cannot be proven from the artifacts");
+  }
+  if (state.phase === "CONTRACT_READY") {
+    if (state.routeFingerprint !== undefined) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not claim a route");
+    }
+    if (Array.isArray(state.selectedGuides) && state.selectedGuides.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have selected guides");
+    }
+    if (Array.isArray(state.requiredGates) && state.requiredGates.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have required gates");
+    }
+    if (Array.isArray(state.satisfiedGates) && state.satisfiedGates.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have satisfied gates");
+    }
+  }
+}
+
+function markerResult(taskId, marker, state, alreadyRepaired) {
+  return {
+    taskId,
+    repaired: alreadyRepaired ? false : true,
+    alreadyRepaired,
+    repairId: marker.details.repairId,
+    phase: state.phase,
+    reconstructedPhase: marker.details.reconstructedPhase,
+    markerEventSeq: marker.seq,
+  };
+}
+
+async function verifyExistingRepair(target, packageRoot, taskId, ledger) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (!anchor || !ledger.valid) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Existing contract bootstrap repair marker is invalid or the repaired ledger is no longer strict");
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (contract.fingerprint !== anchor.details.contractFingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Contract fingerprint no longer matches the repair marker");
+  }
+  const state = await readWorkState(target, { packageRoot, taskId });
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Current task state no longer satisfies the repaired-task invariants", {
+      errors: ownership.errors,
+    });
+  }
+  return markerResult(taskId, { ...anchor.sourceMarker, details: anchor.details }, state, true);
+}
+
+export async function runTaskRepairContractBootstrap({ target, packageRoot, taskId, acknowledgeRepair } = {}) {
+  if (!acknowledgeRepair) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_AUTHORIZATION_REQUIRED, "task-repair-contract-bootstrap requires fresh explicit --acknowledge-repair");
+  }
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+  if (initial.events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) {
+    return verifyExistingRepair(target, packageRoot, effectiveTaskId, initial);
+  }
+  const candidate = isContractBootstrapRepairCandidate(initial.events, initial.errors, effectiveTaskId);
+  if (!candidate) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Ledger does not match the exact contract bootstrap repair signature", { errors: initial.errors });
+  }
+
+  return withProjectClaimsLock(target, "task-repair-contract-bootstrap", async () => {
+    const lock = await readLockInfo(target, effectiveTaskId);
+    const status = classifyLockStaleness(lock);
+    if (status.status === "LIVE") throw repairError(E_TASK_LOCKED, `Task ${effectiveTaskId} has a live mutation lock`);
+    if (status.status === "UNKNOWN" || status.status === "CORRUPT") {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Task ${effectiveTaskId} lock state is ${status.status}`);
+    }
+    if (status.status === "STALE") {
+      const released = await releaseStaleTaskLockIfUnchanged(target, effectiveTaskId, lock);
+      if (!released.released && released.reason !== "LOCK_MISSING") {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE,
+          `Task ${effectiveTaskId} stale lock could not be safely released: ${released.reason}`);
+      }
+    }
+    return withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-repair-contract-bootstrap",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async () => {
+      const locked = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+      if (locked.events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) {
+        return verifyExistingRepair(target, packageRoot, effectiveTaskId, locked);
+      }
+      const lockedCandidate = isContractBootstrapRepairCandidate(locked.events, locked.errors, effectiveTaskId);
+      if (!lockedCandidate
+        || lockedCandidate.duplicateContractEvent.hash !== candidate.duplicateContractEvent.hash
+        || lockedCandidate.duplicateContractCommit.hash !== candidate.duplicateContractCommit.hash) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Ledger changed between inspection and repair lock");
+      }
+      const contract = await readContract(target, packageRoot, { taskId: effectiveTaskId });
+      if (contract.fingerprint !== lockedCandidate.contractFingerprint) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Current contract does not match the canonical historical contract fingerprint");
+      }
+      const route = await readRouteIfProven(target, packageRoot, effectiveTaskId, locked.events, contract.fingerprint);
+      const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
+      assertStateCompatible(state, effectiveTaskId, contract.fingerprint, route);
+      if (!state) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state is required to repair the contract bootstrap defect");
+      }
+      const repository = await currentRepositoryFingerprint(target);
+      const reconstructed = await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId: effectiveTaskId,
+      }, (current) => {
+        assertStateCompatible(current, effectiveTaskId, contract.fingerprint, route);
+        return stateForRepair(current, {
+          taskId: effectiveTaskId,
+          contractFingerprint: contract.fingerprint,
+          route,
+          repository,
+        });
+      });
+      const repairedAt = new Date().toISOString();
+      const details = {
+        repairVersion: CONTRACT_BOOTSTRAP_REPAIR_VERSION,
+        taskId: effectiveTaskId,
+        defect: CONTRACT_BOOTSTRAP_REPAIR_DEFECT,
+        canonicalContractEventSeq: lockedCandidate.canonicalContractEvent.seq,
+        canonicalContractEventHash: lockedCandidate.canonicalContractEvent.hash,
+        duplicateContractEventSeq: lockedCandidate.duplicateContractEvent.seq,
+        duplicateContractEventHash: lockedCandidate.duplicateContractEvent.hash,
+        contractCreateCommitSeq: lockedCandidate.duplicateContractCommit.seq,
+        contractCreateCommitHash: lockedCandidate.duplicateContractCommit.hash,
+        contractCreateTransactionId: lockedCandidate.duplicateContractCommit.details.transactionId,
+        contractFingerprint: contract.fingerprint,
+        reconstructedPhase: reconstructed.phase,
+        routeFingerprint: route?.fingerprint ?? null,
+        previousStateFingerprint: canonicalFingerprint(state),
+        reconstructedStateFingerprint: canonicalFingerprint(reconstructed),
+        reconstructedStateRevision: reconstructed.revision,
+        repairedAt,
+        authorityKind: CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+      };
+      details.repairId = contractBootstrapRepairId(details);
+      assertContractBootstrapRepairDetails(details);
+      const marker = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+        at: repairedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+      return markerResult(effectiveTaskId, marker, reconstructed, false);
+    });
+  });
+}
+
+export function formatTaskRepairContractBootstrapResult(result) {
+  return `taskId: ${result.taskId}\nphase: ${result.phase}\nrepairId: ${result.repairId}\n${result.alreadyRepaired ? "alreadyRepaired: true" : "repaired: true"}\n`;
+}

package/src/commands/test-inventory.js

@@ -0,0 +1,5 @@
+import { runTestInventory as inventory } from "../core/test-intelligence/service.js";
+
+export async function runTestInventory({ target = process.cwd() } = {}) { return inventory({ projectRoot: target }); }
+export function formatTestInventoryResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-prune-plan.js

@@ -0,0 +1,5 @@
+import { buildPrunePlan } from "../core/test-intelligence/prune.js";
+
+export async function runTestPrunePlan({ target, packageRoot, taskId } = {}) { return buildPrunePlan({ target, packageRoot, taskId }); }
+export function formatTestPrunePlanResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-prune-probe.js

@@ -0,0 +1,5 @@
+import { runPruneProbe as probe } from "../core/test-intelligence/prune.js";
+
+export async function runTestPruneProbe({ target, packageRoot, taskId, testId } = {}) { return probe({ target, packageRoot, taskId, testId }); }
+export function formatTestPruneProbeResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-utility.js

@@ -0,0 +1,5 @@
+import { runTestUtility as analyze } from "../core/test-intelligence/service.js";
+
+export async function runTestUtility({ target, packageRoot, taskId, semanticStatus } = {}) { return analyze({ target, packageRoot, taskId, semanticStatus }); }
+export function formatTestUtilityResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/validate-protocol.js

@@ -44,6 +44,10 @@ async function readArtifact(target, relativePath, label) {
   }
 }
 
+function isOptionalContinuityAbsence(item) {
+  return item.label === "continuity" && item.error?.code === "ARTIFACT_MISSING";
+}
+
 import { taskArtifactPath } from "../core/task-paths.js";
 import { withResolvedTask } from "../core/task-command.js";
 
@@ -84,7 +88,12 @@ export async function runValidateProtocol({
     loaded.push({ label, relativePath, ...artifact });
   }
 
-  const readErrors = loaded.filter((item) => item.error).map((item) => item.error);
+  // Continuity is an optional operational-context artifact. Its absence is
+  // represented by evaluateContinuityConformance as NOT_APPLICABLE; only a
+  // present but malformed continuity artifact is a validation failure.
+  const readErrors = loaded
+    .filter((item) => item.error && !isOptionalContinuityAbsence(item))
+    .map((item) => item.error);
   const route = loaded.find((item) => item.label === "route")?.value ?? null;
   const state = loaded.find((item) => item.label === "state")?.value ?? null;
   const receipt = loaded.find((item) => item.label === "receipt")?.value ?? null;

package/src/core/artifact-registry.js

@@ -391,4 +391,28 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Optional external signing-provider bundle; existence alone never establishes a valid signature.",
   }),
+  semanticDecisions: Object.freeze({
+    key: "semanticDecisions",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.decisions}/<decision-id>.json`,
+    schema: "semantic-decision",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "IMMUTABLE_ONCE_WRITTEN",
+    trustRole: "SEMANTIC_DECISION",
+    isPublic: true,
+    isPersisted: true,
+    description: "Fingerprint-bound, normalized Jev semantic decision; never lifecycle, evidence, ownership, installation, or completion authority.",
+  }),
+  testUtility: Object.freeze({
+    key: "testUtility",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.testUtility}`,
+    schema: "test-utility",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "OVERWRITTEN_ON_ANALYSIS",
+    trustRole: "NON_EVIDENCE_TEST_ANALYSIS",
+    isPublic: true,
+    isPersisted: true,
+    description: "Deterministic test inventory and bounded utility analysis; never completion evidence or deletion authority.",
+  }),
 });