@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/adapters/typesafe/normalize.js

@@ -0,0 +1,41 @@
+import { normalizeDecisionResult } from "../../core/decision/result.js";
+import { safeDecisionError } from "../../core/decision/errors.js";
+
+function finiteProbability(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function confidenceFromAnswer(answer) {
+  if (!answer || typeof answer !== "object" || Array.isArray(answer)) return null;
+  if (finiteProbability(answer.confidence)) return answer.confidence;
+  if (answer.type === "noul" && finiteProbability(answer.noul)) {
+    return Math.max(answer.noul, 1 - answer.noul);
+  }
+  return null;
+}
+
+// The live TypeSafe SystemOne result carries per-answer confidence inside each
+// answer (choice.confidence, or the noul judgment probability itself) and no
+// top-level confidence map; translate that into the canonical
+// answer-name -> confidence shape ForgeLoop's decision layer consumes. A
+// provider-reported top-level map remains authoritative per key when present.
+function deriveTypesafeConfidence(raw) {
+  const answers = raw?.answers;
+  const derived = answers && typeof answers === "object" && !Array.isArray(answers)
+    ? Object.fromEntries(Object.entries(answers).map(([name, answer]) => [name, confidenceFromAnswer(answer)]))
+    : {};
+  const provided = raw?.confidence;
+  if (!provided || typeof provided !== "object" || Array.isArray(provided)) return derived;
+  for (const [name, value] of Object.entries(provided)) {
+    if (finiteProbability(value)) derived[name] = value;
+  }
+  return derived;
+}
+
+export function normalizeTypesafeResult(raw, questionSet) {
+  try {
+    return normalizeDecisionResult({ ...raw, confidence: deriveTypesafeConfidence(raw) }, { questionSet });
+  } catch (error) {
+    throw safeDecisionError(error, "E_DECISION_RESULT_INVALID");
+  }
+}

package/src/cli.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { formatStatusResult } from "./commands/status.js";
 import { formatValidateStateResult } from "./commands/validate-state.js";
 import { formatClearStateResult } from "./commands/clear-state.js";
+import { formatCheckpointRevalidateResult } from "./commands/checkpoint-revalidate.js";
 import { formatInspectResult } from "./commands/inspect.js";
 import { formatRouteResult } from "./commands/route.js";
 import { formatValidateProtocolResult } from "./commands/validate-protocol.js";
@@ -54,6 +55,9 @@ import { formatReflectResult } from "./commands/reflect.js";
 import { formatProgressResult } from "./commands/progress.js";
 import { formatRecordDecisionCriterionResult } from "./commands/record-decision-criterion.js";
 import { formatNextActionResult, formatCompactNextActionResult } from "./commands/next.js";
+import { formatDiscoverResult } from "./commands/discover.js";
+import { formatContractCreateResult } from "./commands/contract-create.js";
+import { formatContractReviseResult } from "./commands/contract-revise.js";
 import { formatContinuityResult } from "./commands/continuity.js";
 import { formatRecordContinuityResult } from "./commands/record-continuity.js";
 import { formatReconcileContinuityResult } from "./commands/reconcile-continuity.js";
@@ -66,10 +70,13 @@ import { formatTaskMigrateResult } from "./commands/task-migrate.js";
 import { formatMigrateProtocolResult } from "./commands/migrate-protocol.js";
 import { formatTaskUnlockResult } from "./commands/task-unlock.js";
 import { formatTaskRecoverResult } from "./commands/task-recover.js";
+import { formatTaskAbandonResult } from "./commands/task-abandon.js";
 import { formatTaskResumeResult } from "./commands/task-resume.js";
 import {
   formatTaskRepairLegacyRecoveryResult,
 } from "./commands/task-repair-legacy-recovery.js";
+import { formatTaskRepairContractBootstrapResult } from "./commands/task-repair-contract-bootstrap.js";
+import { formatTaskMigrateContractBootstrapRepairResult } from "./commands/task-migrate-contract-bootstrap-repair.js";
 import { formatTaskLockStatusResult } from "./commands/task-lock-status.js";
 import { formatProtocolInfoResult } from "./commands/protocol-info.js";
 import { formatWorkspaceBindResult } from "./commands/workspace-bind.js";
@@ -92,6 +99,17 @@ import {
 } from "./commands/repository-index.js";
 import { defaultCommandInputValues, validateForgeLoopCommandInput } from "./core/command-input.js";
 import { COMMAND_EXECUTORS } from "./core/command-executors.js";
+import { formatGateRecordResult } from "./commands/gate-record.js";
+import { formatGateRevalidateResult } from "./commands/gate-revalidate.js";
+import { formatDecisionStatusResult } from "./commands/decision-status.js";
+import { formatDecisionShowResult } from "./commands/decision-show.js";
+import { formatContextPlanResult } from "./commands/context-plan.js";
+import { formatModelRouteResult } from "./commands/model-route.js";
+import { formatSemanticPlanResult } from "./commands/semantic-plan.js";
+import { formatTestInventoryResult } from "./commands/test-inventory.js";
+import { formatTestUtilityResult } from "./commands/test-utility.js";
+import { formatTestPrunePlanResult } from "./commands/test-prune-plan.js";
+import { formatTestPruneProbeResult } from "./commands/test-prune-probe.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
 import { CLI_COMMAND_DEFINITIONS, buildOptionLookup, getPositionalDefinitions } from "./core/cli-command-definitions.js";
@@ -349,11 +367,81 @@ function renderJsonOr(options, result, formatter) {
 }
 
 export const COMMAND_HANDLERS = Object.freeze({
+  discover: async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS.discover({ target, packageRoot, options });
+    renderJsonOr(options, result, formatDiscoverResult);
+    return 0;
+  },
+  "contract-create": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["contract-create"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatContractCreateResult);
+    return 0;
+  },
+  "contract-revise": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["contract-revise"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatContractReviseResult);
+    return 0;
+  },
+  "gate-record": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["gate-record"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatGateRecordResult);
+    return 0;
+  },
+  "gate-revalidate": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["gate-revalidate"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatGateRevalidateResult);
+    return 0;
+  },
   "protocol-info": async ({ packageVersion, options }) => {
     const { result } = await COMMAND_EXECUTORS["protocol-info"]({ packageVersion, options });
     renderJsonOr(options, result, formatProtocolInfoResult);
     return 0;
   },
+  "decision-status": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["decision-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatDecisionStatusResult);
+    return 0;
+  },
+  "decision-show": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["decision-show"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatDecisionShowResult);
+    return 0;
+  },
+  "context-plan": async ({ options }) => {
+    const { result } = await COMMAND_EXECUTORS["context-plan"]({ options });
+    renderJsonOr(options, result, formatContextPlanResult);
+    return 0;
+  },
+  "model-route": async ({ options }) => {
+    const { result } = await COMMAND_EXECUTORS["model-route"]({ options });
+    renderJsonOr(options, result, formatModelRouteResult);
+    return 0;
+  },
+  "semantic-plan": async ({ options }) => {
+    const { result } = await COMMAND_EXECUTORS["semantic-plan"]({ options });
+    renderJsonOr(options, result, formatSemanticPlanResult);
+    return 0;
+  },
+  "test-inventory": async ({ target, options }) => {
+    const { result } = await COMMAND_EXECUTORS["test-inventory"]({ target, options });
+    renderJsonOr(options, result, formatTestInventoryResult);
+    return 0;
+  },
+  "test-utility": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["test-utility"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTestUtilityResult);
+    return 0;
+  },
+  "test-prune-plan": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["test-prune-plan"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTestPrunePlanResult);
+    return 0;
+  },
+  "test-prune-probe": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["test-prune-probe"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTestPruneProbeResult);
+    return 0;
+  },
   init: async ({ target, packageRoot, packageVersion, options }) => {
     const { result } = await COMMAND_EXECUTORS.init({ target, packageRoot, packageVersion, options });
     printActions(result.actions);
@@ -784,11 +872,31 @@ export const COMMAND_HANDLERS = Object.freeze({
     renderJsonOr(options, result, formatTaskRecoverResult);
     return 0;
   },
+  "task-abandon": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["task-abandon"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTaskAbandonResult);
+    return 0;
+  },
   "task-resume": async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS["task-resume"]({ target, packageRoot, options });
     renderJsonOr(options, result, formatTaskResumeResult);
     return 0;
   },
+  "task-repair-contract-bootstrap": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["task-repair-contract-bootstrap"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTaskRepairContractBootstrapResult);
+    return 0;
+  },
+  "task-migrate-contract-bootstrap-repair": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["task-migrate-contract-bootstrap-repair"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatTaskMigrateContractBootstrapRepairResult);
+    return 0;
+  },
+  "checkpoint-revalidate": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["checkpoint-revalidate"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatCheckpointRevalidateResult);
+    return 0;
+  },
   "task-repair-legacy-recovery": async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS["task-repair-legacy-recovery"]({ target, packageRoot, options });
     renderJsonOr(options, result, formatTaskRepairLegacyRecoveryResult);

package/src/commands/checkpoint-revalidate.js

@@ -0,0 +1,176 @@
+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 { currentRepositoryFingerprint } from "../core/repository.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { assertTaskMutationAllowed } from "../core/task-claim-state.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import {
+  CHECKPOINT_REVALIDATED_EVENT,
+  assertCheckpointRevalidatedDetails,
+  assertRepositoryFingerprint,
+} from "../core/checkpoint-revalidation.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { sameCanonicalGuideList, resolveEffectiveContractBootstrapRepairAnchor } from "../core/contract-bootstrap-recovery.js";
+import {
+  classifyLoadedWorkState,
+  createWorkState,
+  mutateWorkState,
+  readWorkState,
+} from "../core/work-state.js";
+
+function revalidationError(message, details = {}) {
+  const error = new Error(message);
+  error.code = "E_CHECKPOINT_REVALIDATION_UNSAFE";
+  Object.assign(error, details);
+  return error;
+}
+
+function sameRepositoryFingerprint(left, right) {
+  return left?.branch === right?.branch && left?.head === right?.head;
+}
+
+function assertRouteIdentity(state, contract, route) {
+  if (!route || route.value?.contractFingerprint !== contract.fingerprint
+    || state.routeFingerprint !== route.fingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, route.value.guides)) {
+    throw revalidationError("ROUTED checkpoint route identity cannot be proven safe", {
+      artifacts: [taskArtifactPath(state.taskId, "state"), taskArtifactPath(state.taskId, "route")],
+    });
+  }
+}
+
+async function inspectEligibility(target, packageRoot, taskId) {
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (!state) throw revalidationError("A persisted work-state checkpoint is required");
+  if (state.phase !== "ROUTED") throw revalidationError(`Checkpoint revalidation supports phase ROUTED, found ${state.phase}`);
+
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) throw revalidationError("Checkpoint revalidation requires a structurally valid event ledger", { errors: ledger.errors });
+  if (ledger.events.some((event) => event.event === "EXECUTION_STARTED")) {
+    throw revalidationError("Checkpoint revalidation is unavailable after execution has started");
+  }
+  const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+  if (coherenceErrors.length > 0) throw revalidationError("Checkpoint revalidation requires coherent state and ledger", { errors: coherenceErrors });
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revalidationError("Checkpoint revalidation cannot bypass invalid task ownership", { errors: ownership.ownershipErrors });
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (state.contractFingerprint !== contract.fingerprint) {
+    throw revalidationError("Checkpoint contract identity changed; use the contract revision path");
+  }
+  const route = await readPersistedRoute(target, packageRoot, { taskId });
+  assertRouteIdentity(state, contract, route);
+
+  const freshness = await classifyLoadedWorkState({
+    target,
+    state,
+    contractFile: taskArtifactPath(taskId, "contract"),
+  });
+  const repository = freshness.repository;
+  assertRepositoryFingerprint(repository, "current repository fingerprint", { requireHead: true });
+  const reasons = [...new Set(freshness.reasons)].sort();
+  if (reasons.length === 0) {
+    return { state, contract, route, ledger, repository, freshness, alreadyFresh: true };
+  }
+  if (reasons.length !== 1 || reasons[0] !== "REPOSITORY_CHANGED") {
+    throw revalidationError(`Checkpoint freshness is not repository-only: ${reasons.join(", ")}`);
+  }
+  const repairAnchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (repairAnchor && (repairAnchor.details.contractFingerprint !== contract.fingerprint
+    || repairAnchor.details.routeFingerprint !== route.fingerprint)) {
+    throw revalidationError("Repaired checkpoint identity does not match the current contract and route");
+  }
+  return { state, contract, route, ledger, repository, freshness, repairAnchor, alreadyFresh: false };
+}
+
+function resultFor(taskId, state, repository, event = null, transaction = null, alreadyFresh = false) {
+  return {
+    taskId,
+    revalidated: !alreadyFresh,
+    alreadyFresh,
+    phase: state.phase,
+    previousRevision: event ? event.details.previousStateRevision : state.revision,
+    revalidatedRevision: event ? event.details.revalidatedStateRevision : state.revision,
+    previousRepositoryFingerprint: event?.details.previousRepositoryFingerprint ?? repository,
+    repositoryFingerprint: event?.details.repositoryFingerprint ?? repository,
+    eventSeq: event?.seq ?? null,
+    transactionCommitSeq: transaction?.seq ?? null,
+  };
+}
+
+async function revalidateLocked(target, packageRoot, taskId, transaction) {
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revalidationError("Checkpoint revalidation cannot bypass invalid task ownership", { errors: ownership.ownershipErrors });
+  }
+  await assertTaskMutationAllowed(target, { taskId, packageRoot });
+  const inspected = await inspectEligibility(target, packageRoot, taskId);
+  if (inspected.alreadyFresh) return resultFor(taskId, inspected.state, inspected.repository, null, null, true);
+
+  const before = inspected.state;
+  const previousStateFingerprint = canonicalFingerprint(before);
+  const previousRepositoryFingerprint = structuredClone(before.repositoryFingerprint);
+  const repository = await currentRepositoryFingerprint(target);
+  assertRepositoryFingerprint(repository, "current repository fingerprint", { requireHead: true });
+  if (!sameRepositoryFingerprint(repository, inspected.repository)) {
+    throw revalidationError("Repository identity changed during checkpoint revalidation");
+  }
+  const next = await mutateWorkState(target, {
+    expectedRevision: before.revision,
+    packageRoot,
+    taskId,
+  }, (current) => createWorkState({
+    ...current,
+    repositoryFingerprint: repository,
+    lastUpdated: new Date().toISOString(),
+  }));
+  const details = {
+    phase: next.phase,
+    previousRepositoryFingerprint,
+    repositoryFingerprint: structuredClone(repository),
+    contractFingerprint: next.contractFingerprint,
+    routeFingerprint: next.routeFingerprint,
+    previousStateRevision: before.revision,
+    revalidatedStateRevision: next.revision,
+    previousStateFingerprint,
+    revalidatedStateFingerprint: canonicalFingerprint(next),
+  };
+  assertCheckpointRevalidatedDetails(details);
+  const event = await appendProtocolEvent(target, {
+    taskId,
+    event: CHECKPOINT_REVALIDATED_EVENT,
+    details,
+  }, packageRoot, { taskId });
+  const commitEvent = await appendProtocolEvent(target, {
+    taskId,
+    event: "TRANSACTION_COMMITTED",
+    details: { transactionId: transaction.transactionId, operation: "checkpoint-revalidate" },
+  }, packageRoot, { taskId });
+  return resultFor(taskId, next, repository, event, commitEvent, false);
+}
+
+export async function runCheckpointRevalidate({ target, packageRoot, taskId } = {}) {
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await inspectEligibility(target, packageRoot, effectiveTaskId);
+  if (initial.alreadyFresh) return resultFor(effectiveTaskId, initial.state, initial.repository, null, null, true);
+  return withTaskTransaction({
+    target,
+    taskId: effectiveTaskId,
+    operation: "checkpoint-revalidate",
+    packageRoot,
+    recordCommitEvent: false,
+  }, async (transaction) => revalidateLocked(target, packageRoot, effectiveTaskId, transaction));
+}
+
+export function formatCheckpointRevalidateResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/context-plan.js

@@ -0,0 +1,38 @@
+import { compileContext } from "../core/context-compiler/compiler.js";
+import { normalizeContextCandidates } from "../core/context-compiler/candidates.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { buildContextQuestionSet } from "../core/decision/question-registry.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+
+export async function runContextPlan({ target, packageRoot, taskId, decisionId, profile = "balanced", candidates = [], mandatoryIds = [], provider = null, readOnly = false } = {}) {
+  if (readOnly) return compileContext({ profile, candidates, mandatoryIds });
+  if (target && taskId) {
+    const normalized = normalizeContextCandidates(candidates);
+    const candidateSetFingerprint = canonicalFingerprint(normalized.map((candidate) => ({
+      id: candidate.id, sourceRef: candidate.sourceRef, summary: candidate.summary,
+      required: candidate.required, mandatory: candidate.mandatory,
+    })));
+    const questionSet = buildContextQuestionSet(normalized);
+    const decision = await ensureSemanticDecision({
+      target, packageRoot, taskId, decisionId, provider, allowNetwork: !readOnly,
+      request: {
+        decisionKind: "CONTEXT_PLAN", questionSetId: questionSet.id, questionSet,
+        state: { candidates: normalized.map(({ id, sourceRef, kind, summary, required, mandatory, risk, trust }) => ({ id, sourceRef, kind, summary, required, mandatory, risk, trust })) },
+        candidateIds: normalized.map((candidate) => candidate.id), candidateSetFingerprint,
+      },
+    });
+    return compileContext({ profile, candidates, mandatoryIds, semanticRanker: () => ({ rankedIds: decision.artifact.decision?.rankedIds ?? [], excludedIds: decision.artifact.decision?.excludedIds ?? [] }) });
+  }
+  return compileContext({ profile, candidates, mandatoryIds });
+}
+
+export function formatContextPlanResult(result) {
+  return [
+    `Context plan: ${result.selectedItems}/${result.candidateItems} items`,
+    `Profile: ${result.profile}`,
+    `Selected chars: ${result.selectedChars}/${result.budget.maxChars}`,
+    `Prompt-injection candidates: ${result.promptInjectionIds.length}`,
+    `Fingerprint: ${result.decisionFingerprint}`,
+    "",
+  ].join("\n");
+}