@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/commands/gate-revalidate.js

@@ -0,0 +1,135 @@
+import { optionalConfig } from "../core/preflight-loaders.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { assertSafePath, ensureWithin } from "../core/filesystem.js";
+import { requiredGatesForGuides } from "../core/guide-metadata.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { staleReasons } from "../core/next-action-artifacts.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { taskGatePath, taskArtifactPath } from "../core/task-paths.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { readWorkState } from "../core/work-state.js";
+import { stateIdentityErrors } from "../core/completion-relationships.js";
+import { persistGate, readCanonicalGateArtifactBinding, hashGateFile, readGateIfPresent, validateGateArtifacts } from "../core/gate-artifact.js";
+import {
+  GATE_REVALIDATED_EVENT,
+  assertGateRevalidatedDetails,
+} from "../core/gate-provenance.js";
+
+const POST_EXECUTION_PHASES = new Set([
+  "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING",
+]);
+
+function revalidationError(message, code = "E_GATE_REVALIDATION_UNSAFE", artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+async function hashGateArtifact(target, relativePath) {
+  try {
+    ensureWithin(target, relativePath);
+    const canonical = readCanonicalGateArtifactBinding(target, relativePath);
+    if (canonical) {
+      await assertSafePath(target, relativePath);
+      if (canonical.sha256 === null) throw new Error("artifact is missing from canonical storage");
+      return { path: relativePath, sha256: canonical.sha256 };
+    }
+    const binding = await hashGateFile(target, relativePath);
+    return { path: relativePath, sha256: binding.sha256 };
+  } catch (cause) {
+    throw revalidationError(`Cannot refresh gate artifact ${relativePath}: ${cause.message}`, "E_GATE_REVALIDATION_UNSAFE", [relativePath]);
+  }
+}
+
+async function assertCurrentGateBinding(target, packageRoot, taskId, state, gate) {
+  const contract = await readContract(target, packageRoot, { taskId });
+  const route = await readPersistedRoute(target, packageRoot, { taskId });
+  const identityErrors = stateIdentityErrors({ contract, route, state });
+  if (identityErrors.length > 0) {
+    throw revalidationError(
+      "Gate revalidation requires coherent current contract, route, state, and selected guides",
+      "E_GATE_REVALIDATION_UNSAFE",
+      [taskArtifactPath(taskId, "contract"), taskArtifactPath(taskId, "route"), taskArtifactPath(taskId, "state")],
+    );
+  }
+  const routeStale = staleReasons(state, contract, route);
+  if (routeStale.length > 0) {
+    throw revalidationError("Gate revalidation cannot repair stale contract or route identity", "E_GATE_REVALIDATION_UNSAFE", routeStale.flatMap((reason) => reason.artifacts));
+  }
+  const config = await optionalConfig(target, packageRoot, []);
+  const required = [...new Set([
+    ...(await requiredGatesForGuides(route.value.guides, packageRoot)),
+    ...(config.requiredGates ?? []),
+  ])];
+  if (!required.includes(gate)) {
+    throw revalidationError(`Gate is not required by the active route: ${gate}`, "E_GATE_NOT_REQUIRED", [taskArtifactPath(taskId, "route")]);
+  }
+  return { contract, route };
+}
+
+export async function runGateRevalidate({ target, packageRoot, taskId, gate, acknowledgeStale = false } = {}) {
+  if (!acknowledgeStale) {
+    throw revalidationError("gate-revalidate requires --acknowledge-stale", "E_GATE_REVALIDATION_ACK_REQUIRED");
+  }
+  if (typeof gate !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(gate)) {
+    throw revalidationError(`Invalid gate name: ${gate}`, "E_GATE_INVALID");
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "gate-revalidate", async (ctx) => {
+    const state = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (!state || !POST_EXECUTION_PHASES.has(state.phase)) {
+      throw revalidationError(
+        `gate-revalidate is only available for post-execution repair phases; found ${state?.phase ?? "no phase"}`,
+        "E_GATE_REVALIDATION_PHASE_INVALID",
+        [taskArtifactPath(ctx.taskId, "state")],
+      );
+    }
+    const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+    if (!ledger.valid) throw revalidationError("Gate revalidation requires a valid append-only event ledger", "E_EVENT_INVALID", ledger.errors);
+    const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+    if (coherenceErrors.length > 0) throw revalidationError("Gate revalidation requires coherent state and ledger", "E_PHASE_CHRONOLOGY_INVALID", coherenceErrors);
+    const ownership = await resolveTaskClaimState(target, { taskId: ctx.taskId, packageRoot });
+    if (!ownership.ownershipValid || !ownership.mutationAllowed || ownership.claimState !== "ACTIVE") {
+      throw revalidationError("Gate revalidation cannot bypass active task claim ownership", "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT", ownership.ownershipErrors);
+    }
+    await assertCurrentGateBinding(target, packageRoot, ctx.taskId, state, gate);
+    const existing = await readGateIfPresent(target, gate, packageRoot, { taskId: ctx.taskId });
+    if (!existing || existing.value.status !== "satisfied") {
+      throw revalidationError("Only an existing satisfied gate can be revalidated", "E_GATE_UNVERIFIED", [taskGatePath(ctx.taskId, gate)]);
+    }
+    const stale = await validateGateArtifacts(target, existing.value, packageRoot);
+    if (stale.length === 0) {
+      throw revalidationError("Gate artifacts are already fresh; no revalidation event is required", "E_GATE_REVALIDATION_NOT_STALE", [existing.path]);
+    }
+    const refreshedArtifacts = [];
+    for (const artifact of existing.value.artifacts ?? []) refreshedArtifacts.push(await hashGateArtifact(target, artifact.path));
+    const refreshedGate = { ...existing.value, artifacts: refreshedArtifacts };
+    const persisted = await persistGate(target, refreshedGate, packageRoot, { taskId: ctx.taskId });
+    const details = {
+      gate,
+      previousGateFingerprint: existing.fingerprint,
+      gateFingerprint: persisted.fingerprint,
+      stalePaths: stale.map((entry) => entry.path).sort(),
+    };
+    assertGateRevalidatedDetails(details);
+    const event = await appendProtocolEvent(target, {
+      taskId: ctx.taskId,
+      event: GATE_REVALIDATED_EVENT,
+      details,
+    }, packageRoot, { taskId: ctx.taskId });
+    return {
+      taskId: ctx.taskId,
+      gate,
+      stalePaths: details.stalePaths,
+      gateFingerprint: persisted.fingerprint,
+      eventSeq: event.seq,
+      transactionCommitSeq: event.seq + 1,
+      path: persisted.path ?? persisted.relativePath ?? taskGatePath(ctx.taskId, gate),
+    };
+  });
+}
+
+export function formatGateRevalidateResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/handoff-list.js

@@ -1,10 +1,15 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { listCanonicalHandoffs } from "../core/handoff.js";
 import {
   readHandoffAcceptanceLedger,
   resolveHandoffAcceptance,
 } from "../core/handoff-acceptance.js";
 
-export async function runHandoffList({ target, packageRoot, taskId } = {}) {
+export async function runHandoffList(options = {}) {
+  return withProjectReadSnapshot(options.target, () => projectHandoffList(options));
+}
+
+async function projectHandoffList({ target, packageRoot, taskId } = {}) {
   const handoffs = await listCanonicalHandoffs(target, { packageRoot, taskId });
   const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
   const handoffsWithAcceptance = handoffs.map((handoff) => {

package/src/commands/handoff-show.js

@@ -1,10 +1,15 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { readCanonicalHandoff } from "../core/handoff.js";
 import {
   readHandoffAcceptanceLedger,
   resolveHandoffAcceptance,
 } from "../core/handoff-acceptance.js";
 
-export async function runHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
+export async function runHandoffShow(options = {}) {
+  return withProjectReadSnapshot(options.target, () => projectHandoffShow(options));
+}
+
+async function projectHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
   const artifact = await readCanonicalHandoff(target, { packageRoot, taskId, handoffId });
   const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
   const resolved = resolveHandoffAcceptance({

package/src/commands/migrate-protocol.js

@@ -1,7 +1,7 @@
 import { migrateProtocol } from "../core/protocol-migration.js";
 
-export async function runMigrateProtocol({ target, packageRoot, to, dryRun = false } = {}) {
-  return migrateProtocol(target, { to, dryRun, packageRoot });
+export async function runMigrateProtocol({ target, packageRoot, to, dryRun = false, destination, writersQuiesced = false } = {}) {
+  return migrateProtocol(target, { to, dryRun, packageRoot, destination, writersQuiesced });
 }
 
 export function formatMigrateProtocolResult(result) {

package/src/commands/model-route.js

@@ -0,0 +1,40 @@
+import { projectModelRoute } from "../core/model-router/router.js";
+import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
+import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
+
+export async function runModelRoute(options = {}) {
+  if (options.target && options.taskId) return withProjectReadSnapshot(options.target, () => projectSnapshotModelRoute(options));
+  return projectSnapshotModelRoute(options);
+}
+
+async function projectSnapshotModelRoute({ target, packageRoot, taskId, decisionId, workType, surfaces, risks, platforms, behaviorChange, executableChange, generationRequired, architectureChange, ambiguity, semanticRecommendation, contract }) {
+  if (target && taskId) {
+    const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    // Decision stateFingerprint includes semantic inputs; this reader proves the lifecycle via taskStateFingerprint.
+    delete bindings.stateFingerprint;
+    const decision = await resolveRequiredSemanticDecision({
+      target, packageRoot, taskId, decisionId, decisionKind: "MODEL_ROUTE", currentBindings: bindings,
+    });
+    semanticRecommendation = decision.decision;
+  }
+  return projectModelRoute({
+    input: {
+      workType,
+      surfaces,
+      risks,
+      platforms,
+      behaviorChange,
+      executableChange,
+      generationRequired,
+      architectureChange,
+      ambiguity,
+      contract,
+    },
+    semanticRecommendation,
+  });
+}
+
+export function formatModelRouteResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/next.js

@@ -3,8 +3,14 @@ import { withResolvedTask } from "../core/task-command.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { projectExecutionProfile } from "../core/execution-profile.js";
 import { explainNextAction } from "../core/next-explanation.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
+export async function runNext(options) {
+  const read = () => projectNext(options);
+  return options.target ? withProjectReadSnapshot(options.target, read) : read();
+}
+
+async function projectNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const result = await getNextAction({
       target,

package/src/commands/policy-diff.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { isOperationalArtifactPath, needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore, readOperationalText } from "../storage/operational-context.js";
 import { diffPolicies } from "../core/policy-diff.js";
 import {
   loadEffectiveRules,
@@ -7,6 +9,23 @@ import {
   readTaskPolicySnapshot,
 } from "../core/policy-engine.js";
 
+function canonicalInputPath(target, file) {
+  return path.relative(target, path.resolve(target, file)).replaceAll("\\", "/");
+}
+
+async function readPolicyInput(target, file) {
+  const relative = canonicalInputPath(target, file);
+  const native = readOperationalText(target, relative);
+  if (native.selected) {
+    if (native.text === null) throw Object.assign(new Error(`Policy input does not exist: ${relative}`), { code: "ENOENT" });
+    return JSON.parse(native.text);
+  }
+  if (getOperationalStore(target) && isOperationalArtifactPath(relative)) {
+    throw Object.assign(new Error(`Unsupported canonical policy input: ${relative}`), { code: "E_STORAGE_OPERATION_UNSUPPORTED" });
+  }
+  return JSON.parse(await readFile(path.resolve(target, file), "utf8"));
+}
+
 export async function runPolicyDiff({
   target = process.cwd(),
   packageRoot,
@@ -14,12 +33,15 @@ export async function runPolicyDiff({
   before = null,
   after = null,
 } = {}) {
+  if ([before, after].some(file => file && isOperationalArtifactPath(canonicalInputPath(target, file)))
+    && await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => runPolicyDiff({ target, packageRoot, taskId, before, after }), { readOnly: true });
+  }
   let beforePolicy;
   let afterPolicy;
 
   if (before) {
-    const rawBefore = await readFile(path.resolve(target, before), "utf8");
-    beforePolicy = JSON.parse(rawBefore);
+    beforePolicy = await readPolicyInput(target, before);
   } else if (taskId) {
     const snapshot = await readTaskPolicySnapshot(target, taskId, packageRoot);
     beforePolicy = snapshot ? { rules: snapshot.rules, baseline: { entries: [] } } : { rules: [], baseline: { entries: [] } };
@@ -28,8 +50,7 @@ export async function runPolicyDiff({
   }
 
   if (after) {
-    const rawAfter = await readFile(path.resolve(target, after), "utf8");
-    afterPolicy = JSON.parse(rawAfter);
+    afterPolicy = await readPolicyInput(target, after);
   } else {
     const rules = await loadEffectiveRules(target, packageRoot);
     const baseline = await readBaseline(target, packageRoot);

package/src/commands/progress.js

@@ -1,5 +1,5 @@
 import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
-import { readEvents } from "../core/events.js";
+import { withEventLedgerAudit } from "../core/events.js";
 import { readWorkState } from "../core/work-state.js";
 import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 
@@ -13,16 +13,22 @@ export async function runProgress({ target, packageRoot, taskId, task }) {
   });
   const activeTaskId = resolved.taskId;
 
-  const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
-  const events = await readEvents(target, packageRoot, { taskId: activeTaskId });
-
-  const progress = evaluateProgress({ state, events });
-  return {
-    taskId: activeTaskId ?? state?.taskId ?? "unknown",
-    phase: state?.phase ?? "UNKNOWN",
-    verificationCycle: state?.verificationCycle ?? 1,
-    ...progress,
-  };
+  return withEventLedgerAudit(target, packageRoot, { taskId: activeTaskId }, async ledger => {
+    if (!ledger.valid) {
+      const first = ledger.errors[0] ?? { code: "E_LEDGER_INVALID", message: "Progress requires a valid event ledger" };
+      throw Object.assign(new Error(first.message), { code: first.code });
+    }
+    const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
+    const events = ledger.events;
+
+    const progress = evaluateProgress({ state, events });
+    return {
+      taskId: activeTaskId ?? state?.taskId ?? "unknown",
+      phase: state?.phase ?? "UNKNOWN",
+      verificationCycle: state?.verificationCycle ?? 1,
+      ...progress,
+    };
+  });
 }
 
 export function formatProgressResult(result) {

package/src/commands/record-diagnosis.js

@@ -1,3 +1,4 @@
+import { assertCanonicalPersistence } from "../storage/operational-context.js";
 import { recordDiagnosis } from "../core/diagnosis.js";
 import { recordStructuredDiagnosticCase } from "../core/diagnostic-record.js";
 import { withTaskMutation } from "../core/task-command.js";
@@ -16,7 +17,9 @@ export async function runRecordDiagnosis({
   nextSafeAction,
   taskId,
   task,
+  persistence = null,
 }) {
+  assertCanonicalPersistence(persistence);
   if (file) {
     const legacyFields = [hypothesis, failureClass, settledBy, nextSafeAction].some((value) => value !== undefined && value !== null)
       || (Array.isArray(evidenceRefs) && evidenceRefs.length > 0)

package/src/commands/route.js

@@ -1,13 +1,104 @@
 import { evaluateRoute } from "../core/router.js";
-import { persistRoute } from "../core/route-artifact.js";
+import { persistRoute, readPersistedRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
 import { readConfig } from "../core/config.js";
+import { appendProtocolEvent, readEvents } from "../core/events.js";
 import { detectProjectEvidence } from "../core/project-detection.js";
-import { withTaskMutation } from "../core/task-command.js";
+import { withResolvedTask, withTaskMutation } from "../core/task-command.js";
+import { advanceWorkState } from "../core/phase.js";
+import { mutateWorkState, readWorkState } from "../core/work-state.js";
+import { buildExecutionProfileQuestionSet, buildRouteQuestionSet } from "../core/decision/question-registry.js";
+import { ensureSemanticDecision } from "../core/decision/service.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import {
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
 
-export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task }) {
-  return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "route", async (ctx) => {
-    const effectiveTaskId = ctx?.taskId ?? null;
+function canAppendRepairedRouteWitness({ stateBefore, marker, previousPersistedRouteFingerprint, persistedRoute }) {
+  if (previousPersistedRouteFingerprint === null) {
+    return stateBefore.phase === "CONTRACT_READY"
+      && marker.details.reconstructedPhase === "CONTRACT_READY"
+      && marker.details.routeFingerprint === null;
+  }
+  return persistedRoute.fingerprint !== previousPersistedRouteFingerprint
+    && persistedRoute.value.contractFingerprint === marker.details.contractFingerprint;
+}
+
+function canAppendCanonicalRouteWitness({ stateBefore, previousPersistedRouteFingerprint, persistedRoute }) {
+  return stateBefore?.phase === "ROUTED"
+    && previousPersistedRouteFingerprint !== null
+    && persistedRoute.fingerprint !== previousPersistedRouteFingerprint
+    && stateBefore.contractFingerprint === persistedRoute.value.contractFingerprint;
+}
+
+async function appendRouteWitness({ target, packageRoot, taskId, stateBefore, previousPersistedRouteFingerprint, persistedRoute }) {
+  if (!stateBefore) return;
+  const events = await readEvents(target, packageRoot, { taskId });
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  const canAppend = anchor
+    ? canAppendRepairedRouteWitness({
+      stateBefore,
+      marker: anchor.sourceMarker,
+      previousPersistedRouteFingerprint,
+      persistedRoute,
+    })
+    : canAppendCanonicalRouteWitness({ stateBefore, previousPersistedRouteFingerprint, persistedRoute });
+  if (!canAppend) return;
+  await appendProtocolEvent(target, {
+    taskId,
+    event: "ROUTE_REBOUND",
+    details: {
+      routeFingerprint: persistedRoute.fingerprint,
+      contractFingerprint: persistedRoute.value.contractFingerprint,
+      previousRouteFingerprint: previousPersistedRouteFingerprint,
+    },
+  }, packageRoot, { taskId });
+}
+
+async function persistRoutedState({ target, packageRoot, taskId, route, transaction }) {
+  const stateBefore = await readWorkState(target, { packageRoot, taskId });
+  let previousPersistedRouteFingerprint = null;
+  try {
+    previousPersistedRouteFingerprint = (await readPersistedRoute(target, packageRoot, { taskId })).fingerprint;
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  let contractFingerprint;
+  try {
+    contractFingerprint = (await readContract(target, packageRoot, { taskId })).fingerprint;
+  } catch {
+    contractFingerprint = undefined;
+  }
+  const persistedRoute = await persistRoute(target, route, packageRoot, { contractFingerprint, taskId });
+  const state = await readWorkState(target, { packageRoot, taskId });
+  if (state?.phase === "CONTRACT_READY") {
+    await mutateWorkState(target, {
+      packageRoot,
+      taskId,
+      expectedRevision: state.revision ?? 0,
+    }, () => ({
+      ...state,
+      routeFingerprint: persistedRoute.fingerprint,
+      selectedGuides: [...persistedRoute.value.guides],
+    }));
+    await advanceWorkState(target, "ROUTED", { packageRoot, taskId });
+  }
+  if (transaction?.operation === "route") {
+    await appendRouteWitness({
+      target,
+      packageRoot,
+      taskId,
+      stateBefore,
+      previousPersistedRouteFingerprint,
+      persistedRoute,
+    });
+  }
+}
+
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task, semanticProvider = null, provider = null }) {
+  return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (context) => {
+    const effectiveTaskId = context?.taskId ?? null;
+    const effectiveSemanticProvider = semanticProvider ?? provider;
     let contract = null;
     try {
       contract = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).value;
@@ -21,9 +112,9 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       if (error.code !== "ARTIFACT_MISSING") throw error;
     }
     const projectEvidence = target
-      ? await detectProjectEvidence(target, { claims: ctx?.descriptor?.writeClaims ?? [] })
+      ? await detectProjectEvidence(target, { claims: context?.descriptor?.writeClaims ?? [] })
       : null;
-    const route = evaluateRoute({
+    const routeInput = {
       workType,
       surfaces,
       risks,
@@ -31,22 +122,59 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       behaviorChange,
       executableChange,
       ...(projectEvidence ? { projectEvidence } : {}),
-    }, {
+    };
+    const deterministicRoute = evaluateRoute(routeInput, {
       contract,
-      taskDescriptor: ctx?.descriptor ?? null,
+      taskDescriptor: context?.descriptor ?? null,
       configuredProfile,
       requestedProfile: executionProfile,
     });
-    if (target && packageRoot) {
-      let contractFingerprint;
-      try {
-        contractFingerprint = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).fingerprint;
-      } catch {
-        contractFingerprint = undefined;
-      }
-      await persistRoute(target, route, packageRoot, { contractFingerprint, taskId: effectiveTaskId });
+    let semanticRecommendation = null;
+    if (target && packageRoot && effectiveTaskId) {
+      await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: { decisionKind: "INTAKE", questionSetId: "intake-v1", state: { routeInput: deterministicRoute.input } },
+      });
+      const questionSet = buildRouteQuestionSet(deterministicRoute.guides);
+      const routeDecision = await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: {
+          decisionKind: "ROUTE", questionSetId: questionSet.id, questionSet,
+          state: { routeInput: deterministicRoute.input, eligibleGuides: deterministicRoute.guides.map((guide) => ({ id: guide, reasons: deterministicRoute.reasons[guide] })) },
+          candidateIds: deterministicRoute.guides,
+          candidateSetFingerprint: canonicalFingerprint(deterministicRoute.guides),
+        },
+      });
+      const profileQuestionSet = buildExecutionProfileQuestionSet();
+      const profileDecision = await ensureSemanticDecision({
+        target, packageRoot, taskId: effectiveTaskId, provider: effectiveSemanticProvider,
+        request: {
+          decisionKind: "EXECUTION_PROFILE", questionSetId: profileQuestionSet.id, questionSet: profileQuestionSet,
+          state: {
+            routeInput: deterministicRoute.input,
+            deterministicFloor: deterministicRoute.executionProfile.floor,
+            requestedProfile: deterministicRoute.executionProfile.requested,
+          },
+        },
+      });
+      semanticRecommendation = {
+        guideRelevance: routeDecision.artifact.decision,
+        executionProfile: profileDecision.artifact.decision,
+      };
     }
-    return route;
+    const route = evaluateRoute(routeInput, {
+      contract,
+      taskDescriptor: context?.descriptor ?? null,
+      configuredProfile,
+      requestedProfile: executionProfile,
+      semanticRecommendation,
+    });
+    return withTaskMutation(target, { taskId: effectiveTaskId, packageRoot }, "route", async (ctx) => {
+      if (target && packageRoot) {
+        await persistRoutedState({ target, packageRoot, taskId: effectiveTaskId, route, transaction: ctx?.transaction });
+      }
+      return route;
+    });
   });
 }
 

package/src/commands/semantic-plan.js

@@ -0,0 +1,41 @@
+import { runSemanticPlan as projectPlan } from "../core/semantic-planning/service.js";
+import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
+import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
+
+const PROJECTION_VALUES = Object.freeze({
+  failure: Object.freeze({ implementation: "incorrect implementation", expectation: "stale expectation",
+    state: "state divergence", dependency: "dependency incompatibility", environment: "network/environment" }),
+  diagnosis: Object.freeze({ inspect_state: "inspect state transition", inspect_caller: "inspect caller",
+    inspect_dependency: "inspect dependency behavior", narrow_experiment: "run narrower experiment" }),
+});
+
+function projectionRecommendation(kind, decision) {
+  const values = PROJECTION_VALUES[kind];
+  if (!values) return decision;
+  const field = kind === "failure" ? "failureClass" : "priority";
+  const value = decision[field];
+  if (value === "unknown") return null;
+  return { ...decision, [field]: Object.hasOwn(values, value) ? values[value] : value };
+}
+
+export async function runSemanticPlan(options = {}) {
+  if (options.target && options.taskId) return withProjectReadSnapshot(options.target, () => projectSnapshotSemanticPlan(options));
+  return projectSnapshotSemanticPlan(options);
+}
+
+async function projectSnapshotSemanticPlan({ target, packageRoot, taskId, decisionId, kind, input, semanticRecommendation }) {
+  if (target && taskId) {
+    const decisionKind = { failure: "FAILURE_TRIAGE", diagnosis: "DIAGNOSIS_PRIORITY", review: "REVIEW_PLAN" }[kind];
+    const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    // Decision stateFingerprint includes semantic inputs; this reader proves the lifecycle via taskStateFingerprint.
+    delete bindings.stateFingerprint;
+    const decision = await resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionId, decisionKind, currentBindings: bindings });
+    semanticRecommendation = projectionRecommendation(kind, decision.decision);
+  }
+  return projectPlan({ kind, input, semanticRecommendation });
+}
+
+export function formatSemanticPlanResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}

package/src/commands/status.js

@@ -1,10 +1,15 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { readAndClassifyWorkState } from "../core/work-state.js";
 import { inspectSchemaHealth } from "../core/schema-validation.js";
 import { reconcileContinuity } from "../core/continuity-reconciliation.js";
 import { withResolvedTask } from "../core/task-command.js";
 import { findTaskById } from "../core/task-discovery.js";
 
-export async function runStatus({ target, packageRoot, contractFile = null, taskId, task } = {}) {
+export async function runStatus(options = {}) {
+  return withProjectReadSnapshot(options.target, () => runSelectedStatus(options));
+}
+
+async function runSelectedStatus({ target, packageRoot, contractFile = null, taskId, task } = {}) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const effectiveTaskId = ctx?.taskId ?? null;
     const state = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId: effectiveTaskId });

package/src/commands/storage-backup.js

@@ -0,0 +1,15 @@
+import { getOperationalStore } from "../storage/operational-context.js";
+import { assertSafePath } from "../core/filesystem.js";
+
+export async function runStorageBackup({ target, destination, includeAttachments = false } = {}) {
+  if (typeof destination !== "string" || !destination) throw Object.assign(new Error("storage-backup requires --destination"), { code: "E_CLI_INVOCATION_INVALID" });
+  const store = getOperationalStore(target);
+  if (!store) throw Object.assign(new Error("storage-backup requires an explicitly migrated SQLite project"), { code: "E_STORAGE_MIGRATION_REQUIRED" });
+  const filename = await assertSafePath(target, destination);
+  if (includeAttachments) {
+    const { backupProjectStorage } = await import("../storage/project-backup.js");
+    return backupProjectStorage(store.db, target, filename);
+  }
+  const { backupStorageDatabase } = await import("../storage/backup.js");
+  return backupStorageDatabase(store.db, filename);
+}

package/src/commands/storage-migrate.js

@@ -0,0 +1,5 @@
+import { migrateProjectStorage } from "../storage/migration.js";
+
+export async function runStorageMigrate({ target, destination, writersQuiesced = false, packageRoot } = {}) {
+  return migrateProjectStorage(target, { destination, writersQuiesced, packageRoot });
+}

package/src/commands/storage-migration-resume.js

@@ -0,0 +1,5 @@
+import { resumeProjectStorageMigration } from "../storage/migration.js";
+
+export async function runStorageMigrationResume({ target, destination, expectedOwnerId, writersQuiesced = false, acknowledgeUnboundHandoff = false, packageRoot } = {}) {
+  return resumeProjectStorageMigration(target, { destination, expectedOwnerId, writersQuiesced, acknowledgeUnboundHandoff, packageRoot });
+}