@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/commands/gate-record.js

@@ -0,0 +1,205 @@
+import { lstat, readFile as readBytesFromFile } from "node:fs/promises";
+import path from "node:path";
+
+import { sha256 } from "../core/manifest.js";
+import { ensureWithin, isPathWithin, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { readContract } from "../core/contract.js";
+import { readGuideMetadata, requiredGatesForGuides } from "../core/guide-metadata.js";
+import { optionalConfig } from "../core/preflight-loaders.js";
+import { persistGate } from "../core/gate-artifact.js";
+import { readWorkState } from "../core/work-state.js";
+import { taskArtifactPath, taskGatePath } from "../core/task-paths.js";
+import { withTaskMutation } from "../core/task-command.js";
+import { PROTOCOL_VERSION } from "../core/protocol.js";
+import { staleReasons } from "../core/next-action-artifacts.js";
+import { ARTIFACT_PATHS } from "../core/artifacts.js";
+import { appendProtocolEvent, validateEventLedger } from "../core/events.js";
+
+const STATUSES = new Set(["satisfied", "unverified", "blocked"]);
+const PRE_EXECUTION_PHASES = new Set(["ROUTED", "DESIGNING", "PLANNED"]);
+const MAX_TEXT = 2000;
+const MAX_REPEATABLE_ITEMS = 32;
+const MAX_GATE_ARTIFACT_BYTES = 4 * 1024 * 1024;
+const MAX_GATE_EVIDENCE_BYTES = 64 * 1024;
+const CONFIG_REQUIRED_GATES_MARKER = "config.requiredGates";
+
+const TASK_ARTIFACT_KEYS_BY_PATH = Object.freeze({
+  [ARTIFACT_PATHS.state]: "state",
+  [ARTIFACT_PATHS.contract]: "contract",
+  [ARTIFACT_PATHS.route]: "route",
+});
+
+function gateError(message, options = {}) {
+  const error = new Error(message);
+  error.code = options.code ?? "E_GATE_INVALID";
+  if (options.cause !== undefined) error.cause = options.cause;
+  if (options.artifacts !== undefined) error.artifacts = options.artifacts;
+  return error;
+}
+
+function taskScopedFreshnessPath(taskId, artifactPath) {
+  const key = TASK_ARTIFACT_KEYS_BY_PATH[artifactPath];
+  return key ? taskArtifactPath(taskId, key) : artifactPath;
+}
+
+function bounded(values, name, options = {}) {
+  const maximum = options.maximum ?? MAX_REPEATABLE_ITEMS;
+  if (!Array.isArray(values)) {
+    throw gateError(`${name} must be an array`);
+  }
+  if (values.length > maximum) {
+    throw gateError(`${name} entries must not exceed ${maximum}`);
+  }
+  if (values.some((value) => typeof value !== "string" || value.trim().length === 0 || value.length > MAX_TEXT)) {
+    throw gateError(`${name} entries must be non-empty strings of at most ${MAX_TEXT} characters`);
+  }
+  return values.map((value) => value.trim());
+}
+
+async function hashArtifact(target, artifactPath) {
+  if (typeof artifactPath !== "string" || !artifactPath || path.isAbsolute(artifactPath)) {
+    throw gateError(`Gate artifact must be a project-relative path: ${artifactPath}`);
+  }
+  let candidate;
+  try {
+    candidate = ensureWithin(target, artifactPath);
+  } catch (cause) {
+    throw gateError(`Gate artifact escapes the project: ${artifactPath}`, { cause });
+  }
+  let stat;
+  try {
+    stat = await lstat(candidate);
+  } catch (cause) {
+    throw gateError(`Gate artifact is unavailable: ${artifactPath}`, { cause });
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw gateError(`Gate artifact must be a regular file: ${artifactPath}`);
+  }
+  if (stat.size > MAX_GATE_ARTIFACT_BYTES) {
+    throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
+  }
+  const rootReal = await realpathWithTransientWindowsRetry(target);
+  const candidateReal = await realpathWithTransientWindowsRetry(candidate).catch(() => null);
+  if (!candidateReal || !isPathWithin(rootReal, candidateReal)) {
+    throw gateError(`Gate artifact escapes the project: ${artifactPath}`);
+  }
+  return { path: artifactPath, sha256: sha256(await readBytesFromFile(candidateReal)) };
+}
+
+async function readEvidenceFile(target, evidencePath) {
+  if (typeof evidencePath !== "string" || !evidencePath || path.isAbsolute(evidencePath)) {
+    throw gateError(`Gate evidence must be a project-relative path: ${evidencePath}`);
+  }
+  try {
+    const candidate = ensureWithin(target, evidencePath);
+    const stat = await lstat(candidate);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("not a regular file");
+    if (stat.size > MAX_GATE_EVIDENCE_BYTES) throw new Error(`file exceeds ${MAX_GATE_EVIDENCE_BYTES} bytes`);
+    const rootReal = await realpathWithTransientWindowsRetry(target);
+    const candidateReal = await realpathWithTransientWindowsRetry(candidate);
+    if (!isPathWithin(rootReal, candidateReal)) throw new Error("outside project");
+    const bytes = await readBytesFromFile(candidateReal);
+    if (bytes.length > MAX_GATE_EVIDENCE_BYTES) throw new Error(`file exceeds ${MAX_GATE_EVIDENCE_BYTES} bytes`);
+    const value = JSON.parse(bytes.toString("utf8"));
+    return { path: evidencePath, value };
+  } catch (cause) {
+    throw gateError(`Gate evidence file is invalid: ${evidencePath}`, { cause });
+  }
+}
+
+async function assertCurrentRoute(target, packageRoot, taskId, state, route) {
+  let contract;
+  try {
+    contract = await readContract(target, packageRoot, { taskId });
+  } catch (cause) {
+    throw gateError(`Cannot verify the active route against the current contract: ${cause.message}`, {
+      code: "E_ROUTE_STALE",
+      cause,
+    });
+  }
+  const freshness = staleReasons(state, contract, route);
+  if (freshness.length === 0) return;
+  const reason = freshness.find((entry) => entry.code === "E_ROUTE_STALE") ?? freshness[0];
+  throw gateError(reason.message, {
+    code: reason.code,
+    artifacts: reason.artifacts.map((artifactPath) => taskScopedFreshnessPath(taskId, artifactPath)),
+  });
+}
+
+function hasCurrentEpochGateEvent(events, taskId, gate) {
+  const latestRevisionSeq = events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+  return events.some((event) => event.event === "GATE_SATISFIED"
+    && event.taskId === taskId
+    && event.details?.gate === gate
+    && event.seq > latestRevisionSeq);
+}
+
+export async function runGateRecord({ target, packageRoot, taskId, gate, status, artifacts = [], decisions = [], unknowns = [], assumptions = [], evidenceFile = null } = {}) {
+  if (!STATUSES.has(status)) {
+    throw gateError(`Invalid gate status: ${status}`);
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "gate-record", async (ctx) => {
+    const state = await readWorkState(target, { packageRoot, taskId: ctx.taskId });
+    if (!state || !PRE_EXECUTION_PHASES.has(state.phase)) {
+      throw gateError(`gate-record is only available before execution; found ${state?.phase ?? "no phase"}`, { code: "E_PHASE_FREEZE" });
+    }
+    const route = await readPersistedRoute(target, packageRoot, { taskId: ctx.taskId });
+    await assertCurrentRoute(target, packageRoot, ctx.taskId, state, route);
+    const config = await optionalConfig(target, packageRoot, []);
+    const required = [...new Set([...(await requiredGatesForGuides(route.value.guides, packageRoot)), ...(config.requiredGates ?? [])])];
+    if (!required.includes(gate)) {
+      throw gateError(`Gate is not required by the active route: ${gate}`, { code: "E_GATE_NOT_REQUIRED" });
+    }
+    const artifactPaths = bounded(artifacts, "artifact");
+    const normalizedDecisions = bounded(decisions, "decision");
+    const normalizedUnknowns = bounded(unknowns, "unknown");
+    const approvedAssumptions = bounded(assumptions, "assumption");
+    const fileEvidence = evidenceFile ? await readEvidenceFile(target, evidenceFile) : null;
+    if (status === "satisfied" && (normalizedUnknowns.length > 0 || (normalizedDecisions.length === 0 && !fileEvidence))) {
+      throw gateError("A satisfied gate requires no unknowns and at least one decision");
+    }
+    const hashedArtifacts = [];
+    for (const artifactPath of artifactPaths) hashedArtifacts.push(await hashArtifact(target, artifactPath));
+    const guideMetadata = await readGuideMetadata(packageRoot);
+    const requiredBy = [
+      ...route.value.guides.filter((guide) => (guideMetadata[guide]?.requiresGates ?? []).includes(gate)),
+      ...((config.requiredGates ?? []).includes(gate) ? [CONFIG_REQUIRED_GATES_MARKER] : []),
+    ];
+    const value = {
+      schemaVersion: 1,
+      protocolVersion: PROTOCOL_VERSION,
+      taskId: ctx.taskId,
+      gate,
+      status,
+      requiredBy,
+      artifacts: hashedArtifacts,
+      decisions: normalizedDecisions,
+      unknowns: normalizedUnknowns,
+      approvedAssumptions,
+      evidence: [
+        ...normalizedDecisions.map((decision) => ({ kind: "CALLER_RECORDED", authority: "CALLER", text: decision })),
+        ...(fileEvidence ? [{ kind: "CALLER_RECORDED", authority: "CALLER", path: fileEvidence.path, details: fileEvidence.value }] : []),
+      ],
+    };
+    const persisted = await persistGate(target, value, packageRoot, { taskId: ctx.taskId });
+    if (status === "satisfied") {
+      const ledger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
+      if (!ledger.valid) {
+        throw gateError("gate-record requires a valid event ledger", { code: "E_EVENT_INVALID", artifacts: ledger.errors });
+      }
+      if (!hasCurrentEpochGateEvent(ledger.events, ctx.taskId, gate)) {
+        await appendProtocolEvent(target, {
+          taskId: ctx.taskId,
+          event: "GATE_SATISFIED",
+          details: { gate },
+        }, packageRoot, { taskId: ctx.taskId });
+      }
+    }
+    return { taskId: ctx.taskId, gate, status, path: persisted.path ?? persisted.relativePath ?? taskGatePath(ctx.taskId, gate), artifacts: hashedArtifacts };
+  });
+}
+
+export function formatGateRecordResult(result) {
+  return `gate: ${result.gate}\nstatus: ${result.status}\n`;
+}

package/src/commands/gate-revalidate.js

@@ -0,0 +1,137 @@
+import { lstat } from "node:fs/promises";
+
+import { optionalConfig } from "../core/preflight-loaders.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { ensureWithin, isPathWithin, readBytes, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+import { sha256 } from "../core/manifest.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, 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) {
+  let artifactPath;
+  try {
+    artifactPath = ensureWithin(target, relativePath);
+    const stat = await lstat(artifactPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("artifact must be a regular file");
+    const rootReal = await realpathWithTransientWindowsRetry(target);
+    const artifactReal = await realpathWithTransientWindowsRetry(artifactPath);
+    if (!isPathWithin(rootReal, artifactReal)) throw new Error("artifact resolves outside the project");
+    return { path: relativePath, sha256: sha256(await readBytes(artifactReal)) };
+  } 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/model-route.js

@@ -0,0 +1,32 @@
+import { projectModelRoute } from "../core/model-router/router.js";
+import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
+import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+
+export async function runModelRoute({ 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);
+    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

@@ -2,8 +2,9 @@ import { getNextAction } from "../core/next-action.js";
 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";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false }) {
+export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const result = await getNextAction({
       target,
@@ -12,7 +13,8 @@ export async function runNext({ target, packageRoot, taskId, task, authorityCont
       authorityContext,
       runtimeContext,
     });
-    if (!compact) return result;
+    const explained = explain ? { ...result, explanation: explainNextAction(result) } : result;
+    if (!compact) return explained;
     const compactTaskId = ctx?.taskId ?? (result.taskId && result.taskId !== "unknown" ? result.taskId : null);
     let profile = null;
     try {
@@ -23,12 +25,13 @@ export async function runNext({ target, packageRoot, taskId, task, authorityCont
     }
     return {
       taskId: compactTaskId ?? result.taskId,
-      phase: result.currentPhase,
+      phase: explained.currentPhase,
       profile,
-      nextAction: result.nextAction,
-      command: result.commandSpecs?.[0]?.argv ?? [],
-      terminal: result.terminal,
-      errors: result.reasonCodes ?? result.reasons?.map((reason) => reason.code) ?? [],
+      nextAction: explained.nextAction,
+      command: explained.commandSpecs?.[0]?.argv ?? [],
+      terminal: explained.terminal,
+      errors: explained.reasonCodes ?? explained.reasons?.map((reason) => reason.code) ?? [],
+      ...(explained.explanation ? { explanation: explained.explanation } : {}),
     };
   });
 }
@@ -68,6 +71,15 @@ export function formatNextActionResult(result) {
     lines.push(...result.missingArtifacts.map((artifact) => `- ${artifact}`));
   }
   if (result.terminal) lines.push("STATE: TERMINAL");
+  if (result.explanation) {
+    lines.push("EXPLANATION (BOUNDED, READ-ONLY):");
+    lines.push(`- ${result.explanation.summary}`);
+    for (const item of result.explanation.reasons) {
+      lines.push(`- ${item.code}: ${item.requiredChange}`);
+      if (item.safeArtifacts.length > 0) lines.push(`  ARTIFACTS: ${item.safeArtifacts.join(", ")}`);
+    }
+    lines.push(`- ACTION KIND: ${result.explanation.actionKind}`);
+  }
   return `${lines.join("\n")}\n`;
 }
 

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,17 @@
+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";
+
+export async function runSemanticPlan({ 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);
+    const decision = await resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionId, decisionKind, currentBindings: bindings });
+    semanticRecommendation = decision.decision;
+  }
+  return projectPlan({ kind, input, semanticRecommendation });
+}
+
+export function formatSemanticPlanResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}