@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/commands/contract-create.js

@@ -0,0 +1,264 @@
+import { readFile } from "node:fs/promises";
+
+import { createPresetContract } from "../core/contract-presets.js";
+import { contractFingerprint, readContract, validateContract, writeContract } from "../core/contract.js";
+import { appendProtocolEvent, readEvents, validateEventLedger } from "../core/events.js";
+import { isContractBootstrapRepairCandidate } from "../core/contract-bootstrap-recovery.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { createWorkState, initializeWorkState, readWorkState } from "../core/work-state.js";
+import { ensureWithin, fileExists } from "../core/filesystem.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import {
+  buildResumableWorkStateFields,
+  deriveResumePhaseFromLedger,
+} from "../core/resumability.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+
+function bootstrapInconsistent(message, candidate = false) {
+  const error = new Error(message);
+  error.code = candidate ? "E_CONTRACT_BOOTSTRAP_REPAIR_AVAILABLE" : "E_CONTRACT_BOOTSTRAP_INCONSISTENT";
+  return error;
+}
+
+async function hasValidatedContractHistory(target, packageRoot, taskId) {
+  if (!target || !packageRoot || !taskId) return false;
+  const events = await readEvents(target, packageRoot, { taskId });
+  return events.some((event) => event.event === "CONTRACT_VALIDATED");
+}
+
+/**
+ * Resolves the reconstruction projection for a task with a validated ledger
+ * whose work-state checkpoint is missing.
+ *
+ * Ownership rule: the existing canonical contract plus the validated
+ * CONTRACT_VALIDATED event are authoritative. Caller-supplied --preset or
+ * --contract-file material is only used to prove fingerprint equivalence; the
+ * preset generator never redefines historical truth. Reconstruction is
+ * recovery, not contract creation.
+ *
+ * Fail-closed rule: the ledger proves which lifecycle milestones happened.
+ * A ROUTE_VALIDATED event with a missing, malformed, or differently-bound
+ * route artifact cannot be downgraded to CONTRACT_READY; that would regress
+ * the lifecycle and allow a later route command to append a duplicate
+ * ROUTE_VALIDATED milestone.
+ */
+async function loadReconstructionEvidence(target, packageRoot, taskId) {
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) {
+    const candidate = isContractBootstrapRepairCandidate(ledger.events, ledger.errors, taskId);
+    const error = bootstrapInconsistent(
+      candidate
+        ? "The exact contract bootstrap defect requires task-repair-contract-bootstrap"
+        : "Existing contract has an inconsistent ledger; cannot overwrite",
+      !!candidate,
+    );
+    error.next = candidate
+      ? `forgeloop task-repair-contract-bootstrap --task ${taskId} --acknowledge-repair --json`
+      : undefined;
+    throw error;
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (!ledger.events.some((event) => event.event === "CONTRACT_VALIDATED"
+    && event.details?.contractFingerprint === contract.fingerprint)) {
+    throw bootstrapInconsistent("Existing contract is not bound to a valid CONTRACT_VALIDATED event");
+  }
+
+  const routeValidated = ledger.events.some((event) => event.event === "ROUTE_VALIDATED");
+  const route = await readPersistedRoute(target, packageRoot, { taskId }).catch((error) => ({
+    __reconstructionError: error,
+  }));
+  if (routeValidated) {
+    if (route?.__reconstructionError || !route?.fingerprint) {
+      throw bootstrapInconsistent(
+        "Ledger contains ROUTE_VALIDATED but the route artifact is missing or malformed; reconstruction must not downgrade the lifecycle",
+      );
+    }
+    if (route.value?.contractFingerprint !== undefined
+      && route.value.contractFingerprint !== contract.fingerprint) {
+      throw bootstrapInconsistent(
+        "Persisted route artifact is bound to a different contract than the validated contract",
+      );
+    }
+  }
+  const scopedEvents = ledger.events.filter((event) => event.taskId === taskId);
+  const resumedPhase = routeValidated
+    ? (await deriveResumePhaseFromLedger(target, packageRoot, taskId) ?? "ROUTED")
+    : "CONTRACT_READY";
+  const projection = buildResumableWorkStateFields({ events: scopedEvents, resumedPhase });
+  return { ledger, contract, route: routeValidated ? route : null, projection };
+}
+
+async function reconstructFromExistingContract(target, packageRoot, taskId, requestedFingerprint = null) {
+  const { contract, route, projection } = await loadReconstructionEvidence(target, packageRoot, taskId);
+  if (requestedFingerprint !== null && requestedFingerprint !== contract.fingerprint) {
+    throw bootstrapInconsistent("A different contract already exists for this task; contract-create is not contract-revise");
+  }
+  const repositoryFingerprint = await currentRepositoryFingerprint(target);
+  const reconstructedState = createWorkState({
+    taskId,
+    contractFingerprint: contract.fingerprint,
+    ...(route ? { routeFingerprint: route.fingerprint } : {}),
+    repositoryFingerprint,
+    phase: projection.phase,
+    selectedGuides: route ? [...route.value.guides] : [],
+    requiredGates: [],
+    satisfiedGates: [],
+    completedSteps: projection.completedSteps,
+    pendingSteps: projection.pendingSteps,
+    ...(projection.verificationCycle !== undefined ? { verificationCycle: projection.verificationCycle } : {}),
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+  });
+  await initializeWorkState(target, reconstructedState, { packageRoot, taskId });
+  return {
+    taskId,
+    phase: projection.phase,
+    idempotent: true,
+    contractFingerprint: contract.fingerprint,
+    reconstructed: true,
+  };
+}
+
+export async function runContractCreate({ target, packageRoot, taskId, task, contractFile = null, preset = null, semanticProvider = null } = {}) {
+  if (!preset && !contractFile) throw new Error("contract-create requires --preset or --contract-file");
+  if (preset && contractFile) throw new Error("contract-create accepts either --preset or --contract-file, not both");
+
+  const effectiveTaskId = taskId ?? task;
+  const hasCanonicalContract = await hasValidatedContractHistory(target, packageRoot, effectiveTaskId);
+  if (target && packageRoot && effectiveTaskId && !hasCanonicalContract) {
+    await ensureSemanticDecision({
+      target, packageRoot, taskId: effectiveTaskId, provider: semanticProvider,
+      request: {
+        decisionKind: "CONTRACT_APPLICABILITY", questionSetId: "contract-v1",
+        state: { source: preset ? "preset" : "contract-file", preset: preset ?? null },
+      },
+    });
+  }
+  return withTaskMutation(target, { taskId: effectiveTaskId, packageRoot }, "contract-create", async (ctx) => {
+    const events = await readEvents(target, packageRoot, { taskId: ctx.taskId });
+    if (!events.some((event) => event.event === "DISCOVERY_STARTED")) {
+      const error = new Error("Contract creation requires completed discovery");
+      error.code = "E_DISCOVERY_REQUIRED";
+      throw error;
+    }
+    const existingState = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (existingState) {
+      if (existingState.phase !== "CONTRACT_READY") throw new Error("Contract already exists beyond the contract-ready phase");
+      const existingContract = await readContract(target, packageRoot, { taskId: ctx.taskId });
+      const existingLedger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      if (!existingLedger.valid) {
+        const candidate = isContractBootstrapRepairCandidate(existingLedger.events, existingLedger.errors, ctx.taskId);
+        const error = bootstrapInconsistent(
+          candidate
+            ? "The exact contract bootstrap defect requires task-repair-contract-bootstrap"
+            : "Existing contract checkpoint has an invalid event ledger",
+          !!candidate,
+        );
+        error.next = candidate ? `forgeloop task-repair-contract-bootstrap --task ${ctx.taskId} --acknowledge-repair --json` : undefined;
+        throw error;
+      }
+      if (existingState.contractFingerprint !== existingContract.fingerprint
+        || !existingLedger.events.some((event) => event.event === "CONTRACT_VALIDATED"
+          && event.details?.contractFingerprint === existingContract.fingerprint)) {
+        throw bootstrapInconsistent("Existing contract checkpoint is not bound to its validated contract event");
+      }
+      return { taskId: ctx.taskId, phase: existingState.phase, idempotent: true, contractFingerprint: existingContract.fingerprint };
+    }
+
+    // Reconstruction precedes preset generation: when the task already has a
+    // canonical contract, recover from it without generating a replacement
+    // candidate first. The requested preset/file contract is only compared by
+    // fingerprint to prove idempotent equivalence; it never redefines the
+    // canonical historical contract.
+    const existingContractPath = taskArtifactPath(ctx.taskId, "contract");
+    if (await fileExists(ensureWithin(target, existingContractPath)).catch(() => false)) {
+      const existingContract = await readContract(target, packageRoot, { taskId: ctx.taskId });
+      const existingLedger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      const validatedContractEvents = existingLedger.events.filter(
+        (event) => event.event === "CONTRACT_VALIDATED",
+      );
+
+      // task-create persists the proposed contract before contract-create has
+      // validated it. That artifact is not yet canonical history, so preserve
+      // ordinary first-time contract creation when no CONTRACT_VALIDATED event
+      // exists. Once validation history exists, reconstruction must be
+      // authoritative and fail closed on any binding mismatch.
+      if (validatedContractEvents.length > 0) {
+        if (!validatedContractEvents.some(
+          (event) => event.details?.contractFingerprint === existingContract.fingerprint,
+        )) {
+          throw bootstrapInconsistent("Existing contract is not bound to a valid CONTRACT_VALIDATED event");
+        }
+
+        let requestedFingerprint = null;
+        if (contractFile) {
+          const source = ensureWithin(target, contractFile);
+          if (await fileExists(source).catch(() => false)) {
+            try {
+              const candidate = { ...JSON.parse(await readFile(source, "utf8")), taskId: ctx.taskId };
+              await validateContract(candidate, packageRoot);
+              requestedFingerprint = contractFingerprint(candidate);
+            } catch {
+              requestedFingerprint = undefined;
+            }
+          }
+        }
+        // A preset selector is not historical contract authority. If the
+        // caller supplied a replacement file, compare it; otherwise recover
+        // the persisted contract independently of current preset generation.
+        return reconstructFromExistingContract(
+          target,
+          packageRoot,
+          ctx.taskId,
+          requestedFingerprint ?? null,
+        );
+      }
+    }
+
+    let contract;
+    if (preset) {
+      contract = createPresetContract({ taskId: ctx.taskId, preset, claims: ctx.descriptor.writeClaims });
+    } else {
+      const source = ensureWithin(target, contractFile);
+      if (!(await fileExists(source))) throw new Error(`Specified contract file not found: ${contractFile}`);
+      contract = JSON.parse(await readFile(source, "utf8"));
+      contract = { ...contract, taskId: ctx.taskId };
+    }
+    await validateContract(contract, packageRoot);
+    const fingerprint = contractFingerprint(contract);
+
+    await writeContract(target, contract, packageRoot, { taskId: ctx.taskId });
+    const repositoryFingerprint = await currentRepositoryFingerprint(target);
+    await initializeWorkState(target, createWorkState({
+      taskId: ctx.taskId,
+      contractFingerprint: fingerprint,
+      repositoryFingerprint,
+      phase: "CONTRACT_READY",
+      selectedGuides: [],
+      requiredGates: [],
+      satisfiedGates: [],
+      completedSteps: ["contract"],
+      pendingSteps: ["route", "planning", "implementation", "verification"],
+      requiredArtifacts: [],
+      checks: [],
+      failures: [],
+      blockers: [],
+      verificationEvidence: [],
+    }), { packageRoot, taskId: ctx.taskId });
+    await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: "CONTRACT_VALIDATED",
+      details: { contractFingerprint: fingerprint },
+    }, packageRoot, { taskId: ctx.taskId });
+    return { taskId: ctx.taskId, phase: "CONTRACT_READY", idempotent: false, contractFingerprint: fingerprint };
+  });
+}
+
+export function formatContractCreateResult(result) {
+  return `phase: ${result.phase}\n${result.idempotent ? "idempotent: true\n" : ""}`;
+}

package/src/commands/contract-revise.js

@@ -0,0 +1,236 @@
+import { createPresetContract } from "../core/contract-presets.js";
+import {
+  contractFingerprint,
+  readContract,
+  validateContract,
+  writeContract,
+} from "../core/contract.js";
+import {
+  appendProtocolEvent,
+  validateEventLedger,
+  validateStateLedgerCoherence,
+} from "../core/events.js";
+import { canonicalFingerprint, readJsonArtifact } from "../core/artifacts.js";
+import { resolveEffectiveContractBootstrapRepairAnchor } from "../core/contract-bootstrap-recovery.js";
+import {
+  CONTRACT_REVISED_EVENT,
+  assertContractRevisedDetails,
+} from "../core/contract-revision.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
+import { assertTaskMutationAllowed, resolveTaskClaimState } from "../core/task-claim-state.js";
+import { assertWorkspaceBinding } from "../core/workspace-binding.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { mutateWorkState, readWorkState } from "../core/work-state.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { assertStateIdentity } from "../core/completion-relationships.js";
+
+const REVISION_PHASES = new Set(["CONTRACT_READY", "ROUTED", "PLANNED"]);
+
+function revisionError(message, artifacts = []) {
+  const error = new Error(message);
+  error.code = "E_CONTRACT_REVISION_UNSAFE";
+  if (artifacts.length > 0) error.artifacts = artifacts;
+  return error;
+}
+
+async function loadCandidate({ target, packageRoot, taskId, contractFile, preset, claims }) {
+  if (preset) return createPresetContract({ taskId, preset, claims });
+  let artifact;
+  try {
+    artifact = await readJsonArtifact(target, contractFile, "current-contract", packageRoot);
+  } catch (error) {
+    throw revisionError(`Unable to read replacement contract: ${error.message}`, error.artifacts ?? [contractFile]);
+  }
+  if (artifact.value.taskId !== taskId) {
+    throw revisionError(
+      `Replacement contract taskId "${artifact.value.taskId}" does not match requested taskId "${taskId}"`,
+      [contractFile],
+    );
+  }
+  return artifact.value;
+}
+
+function revisionStateProjection(state, contractFingerprintValue, phase) {
+  const next = {
+    ...state,
+    contractFingerprint: contractFingerprintValue,
+    phase,
+    requiredGates: [],
+    satisfiedGates: [],
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+    completedSteps: phase === "CONTRACT_READY" ? ["contract"] : ["contract", "route"],
+    pendingSteps: phase === "CONTRACT_READY"
+      ? ["route", "planning", "implementation", "verification"]
+      : ["planning", "implementation", "verification"],
+  };
+  delete next.evidenceCoverage;
+  delete next.lastCompletionAttempt;
+  delete next.diagnosedHypothesis;
+  // The revision event carries the explicit PLANNED -> ROUTED rewind proof.
+  // Do not feed the old lifecycle transition marker back into createWorkState:
+  // the global transition table must remain forward-only.
+  delete next.previousPhase;
+  return next;
+}
+
+async function inspectRevisionEligibility({ target, packageRoot, taskId, context }) {
+  const state = await readWorkState(target, { packageRoot, taskId });
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (!state) throw revisionError("Contract revision requires a current work-state checkpoint");
+  if (state.taskId !== taskId) throw revisionError("Work-state task identity does not match the selected task");
+  if (!REVISION_PHASES.has(state.phase)) {
+    throw revisionError(`Contract revision is unavailable in phase ${state.phase}`);
+  }
+  if (state.contractFingerprint !== contract.fingerprint) {
+    throw revisionError("Current work-state is not bound to the current contract artifact");
+  }
+  const ledger = await validateEventLedger(target, packageRoot, { taskId });
+  if (!ledger.valid) throw revisionError("Contract revision requires a valid event ledger", ledger.errors);
+  if (ledger.events.some((event) => event.event === "EXECUTION_STARTED")) {
+    throw revisionError("Contract revision is unavailable after execution has started");
+  }
+  const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+  if (coherenceErrors.length > 0) {
+    throw revisionError("Contract revision cannot repair an inconsistent task", coherenceErrors);
+  }
+  const repairAnchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (repairAnchor) {
+    throw revisionError("Contract revision is unavailable for tasks with a contract-bootstrap repair or migration anchor");
+  }
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid || !ownership.mutationAllowed) {
+    throw revisionError("Contract revision cannot bypass invalid task ownership", ownership.ownershipErrors);
+  }
+  if (!context?.descriptor || context.descriptor.taskId !== taskId) {
+    throw revisionError("A valid task descriptor is required for contract revision");
+  }
+  return { state, contract, ledger, ownership };
+}
+
+async function assertPreRevisionRouteIdentity({ target, packageRoot, taskId, state, contract }) {
+  if (state.phase === "CONTRACT_READY") return;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId });
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw revisionError(
+      `Contract revision requires a valid current route: ${error.message}`,
+      error.artifacts ?? [],
+    );
+  }
+}
+
+async function reviseLocked({ target, packageRoot, taskId, context, contractFile, preset, transaction }) {
+  await assertTaskMutationAllowed(target, { taskId, packageRoot });
+  await assertWorkspaceBinding(target, { taskId, packageRoot, operation: "contract-revise" });
+  const inspected = await inspectRevisionEligibility({ target, packageRoot, taskId, context });
+  const candidate = await loadCandidate({
+    target,
+    packageRoot,
+    taskId,
+    contractFile,
+    preset,
+    claims: context.descriptor.writeClaims,
+  });
+  await validateContract(candidate, packageRoot);
+  const nextFingerprint = contractFingerprint(candidate);
+  if (nextFingerprint === inspected.contract.fingerprint) {
+    return {
+      taskId,
+      revised: false,
+      alreadyCurrent: true,
+      phase: inspected.state.phase,
+      contractFingerprint: inspected.contract.fingerprint,
+      revision: inspected.state.revision,
+    };
+  }
+
+  await assertPreRevisionRouteIdentity({
+    target,
+    packageRoot,
+    taskId,
+    state: inspected.state,
+    contract: inspected.contract,
+  });
+
+  const before = inspected.state;
+  const nextPhase = before.phase === "PLANNED" ? "ROUTED" : before.phase;
+  const previousRouteFingerprint = before.routeFingerprint ?? null;
+  const projected = revisionStateProjection(before, nextFingerprint, nextPhase);
+  await writeContract(target, candidate, packageRoot, { taskId, operation: "contract-revise" });
+  const next = await mutateWorkState(target, {
+    expectedRevision: before.revision,
+    packageRoot,
+    taskId,
+  }, () => projected);
+  const details = {
+    previousContractFingerprint: inspected.contract.fingerprint,
+    contractFingerprint: nextFingerprint,
+    previousPhase: before.phase,
+    phase: next.phase,
+    previousStateRevision: before.revision,
+    revisedStateRevision: next.revision,
+    previousStateFingerprint: canonicalFingerprint(before),
+    revisedStateFingerprint: canonicalFingerprint(next),
+    previousRouteFingerprint,
+  };
+  assertContractRevisedDetails(details);
+  const event = await appendProtocolEvent(target, {
+    taskId,
+    event: CONTRACT_REVISED_EVENT,
+    details,
+  }, packageRoot, { taskId });
+  const commit = await appendProtocolEvent(target, {
+    taskId,
+    event: "TRANSACTION_COMMITTED",
+    details: { transactionId: transaction.transactionId, operation: "contract-revise" },
+  }, packageRoot, { taskId });
+  return {
+    taskId,
+    revised: true,
+    alreadyCurrent: false,
+    phase: next.phase,
+    previousContractFingerprint: inspected.contract.fingerprint,
+    contractFingerprint: nextFingerprint,
+    previousPhase: before.phase,
+    revision: next.revision,
+    eventSeq: event.seq,
+    transactionCommitSeq: commit.seq,
+  };
+}
+
+export async function runContractRevise({ target, packageRoot, taskId, contractFile = null, preset = null } = {}) {
+  if (!taskId) throw revisionError("contract-revise requires --task");
+  if ((!contractFile && !preset) || (contractFile && preset)) {
+    throw revisionError("contract-revise requires exactly one of --contract-file or --preset");
+  }
+  const context = await resolveTaskContext(target, {
+    taskId,
+    packageRoot,
+    explicitRequired: true,
+    selectionMode: TASK_SELECTION_MODES.MUTATION,
+  });
+  return withTaskTransaction({
+    target,
+    taskId: context.taskId,
+    packageRoot,
+    operation: "contract-revise",
+    recordCommitEvent: false,
+  }, async (transaction) => reviseLocked({
+    target,
+    packageRoot,
+    taskId: context.taskId,
+    context,
+    contractFile,
+    preset,
+    transaction,
+  }));
+}
+
+export function formatContractReviseResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/decision-show.js

@@ -0,0 +1,14 @@
+import { readDecisionArtifact } from "../core/decision/artifact.js";
+
+export async function runDecisionShow({ target, packageRoot, taskId, decisionId } = {}) {
+  if (typeof taskId !== "string" || !taskId || typeof decisionId !== "string" || !decisionId) {
+    const error = new Error("decision-show requires --task and --decision");
+    error.code = "E_DECISION_REQUEST_INVALID";
+    throw error;
+  }
+  return (await readDecisionArtifact(target, taskId, decisionId, packageRoot)).value;
+}
+
+export function formatDecisionShowResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/decision-status.js

@@ -0,0 +1,22 @@
+import { readConfig } from "../core/config.js";
+import { DECISION_DEFAULT_POLICY, DECISION_ENGINE_ID, PINNED_JEV_MODEL } from "../core/decision/constants.js";
+import { normalizeDecisionPolicy } from "../core/decision/policy.js";
+import { createTypesafeEngine } from "../adapters/typesafe/engine.js";
+import { hasTypesafeCredentials } from "../adapters/typesafe/client.js";
+
+export async function runDecisionStatus({ target, packageRoot, health = false } = {}) {
+  let policy = DECISION_DEFAULT_POLICY;
+  try {
+    const config = await readConfig(target, packageRoot);
+    policy = normalizeDecisionPolicy(config.decisionEngine ?? DECISION_DEFAULT_POLICY);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  const result = { required: true, engine: DECISION_ENGINE_ID, model: PINNED_JEV_MODEL, credentials: hasTypesafeCredentials() ? "configured" : "missing", status: hasTypesafeCredentials() ? "configured" : "missing" };
+  if (health) result.health = await createTypesafeEngine({ policy }).health();
+  return result;
+}
+
+export function formatDecisionStatusResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/discover.js

@@ -0,0 +1,41 @@
+import { appendProtocolEvent, readEvents, validateEventLedger } from "../core/events.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+function initialHistory(events, taskId) {
+  if (events.length < 2) return false;
+  return events[0]?.taskId === taskId
+    && events[0]?.event === "TASK_RECEIVED"
+    && events[1]?.taskId === taskId
+    && events[1]?.event === "TRANSACTION_COMMITTED"
+    && events[1]?.details?.operation === "task-create";
+}
+
+export async function runDiscover({ target, packageRoot, taskId, task } = {}) {
+  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "discover", async (ctx) => {
+    const events = await readEvents(target, packageRoot, { taskId: ctx.taskId });
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+    if (!ledger.valid) {
+      const error = new Error("Initial discovery requires a valid task event ledger");
+      error.code = "E_LEDGER_INVALID";
+      error.artifacts = ledger.errors.flatMap((entry) => entry.artifacts ?? []);
+      throw error;
+    }
+    if (!initialHistory(events, ctx.taskId)) {
+      const error = new Error("Initial discovery requires the canonical task-create history");
+      error.code = "E_INITIAL_LIFECYCLE_INVALID";
+      throw error;
+    }
+    const existing = events.find((event) => event.event === "DISCOVERY_STARTED");
+    if (existing) return { taskId: ctx.taskId, phase: "DISCOVERING", idempotent: true, eventSeq: existing.seq };
+    const event = await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: "DISCOVERY_STARTED",
+      details: { source: "canonical-discover" },
+    }, packageRoot, { taskId: ctx.taskId });
+    return { taskId: ctx.taskId, phase: "DISCOVERING", idempotent: false, eventSeq: event.seq };
+  });
+}
+
+export function formatDiscoverResult(result) {
+  return `phase: ${result.phase}\n${result.idempotent ? "idempotent: true\n" : ""}`;
+}

package/src/commands/doctor.js

@@ -9,6 +9,19 @@ import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
 import { getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
 import { searchRepository } from "../repository-index/search.js";
 import { getPersistentTransportStatus } from "../persistent-transport/client.js";
+import { hasTypesafeCredentials } from "../adapters/typesafe/client.js";
+import { PINNED_JEV_MODEL } from "../core/decision/constants.js";
+
+function semanticDecisionPlaneFinding() {
+  const credentialState = hasTypesafeCredentials() ? "credentials configured" : "credentials missing";
+  return finding(
+    "semantic-decision-plane",
+    "info",
+    ".forgeloop/config.json",
+    `Semantic decision plane: ${credentialState}; pinned model ${PINNED_JEV_MODEL}.`,
+    "Set TYPESAFE_API_KEY in the host environment before invoking a new semantic decision; recovery and inspection remain local.",
+  );
+}
 
 function finding(code, severity, relativePath, message, remediation = null, evidence = null) {
   const evidenceRecord = evidence && typeof evidence === "object"
@@ -392,6 +405,8 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     findings,
   });
 
+  findings.push(semanticDecisionPlaneFinding());
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {