@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/src/core/handoff-acceptance.js

@@ -0,0 +1,277 @@
+import { canonicalFingerprint } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
+import { compareRepositoryFingerprint, readCanonicalHandoff } from "./handoff.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
+import { withTaskTransaction } from "./transaction.js";
+import { getPackageRoot } from "./templates.js";
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+} from "./portable-context.js";
+import {
+  E_HANDOFF_ACCEPTANCE_UNBOUND,
+  E_HANDOFF_STALE,
+  E_HANDOFF_ALREADY_ACCEPTED,
+  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+} from "./error-codes.js";
+
+function acceptanceError(code, message) {
+  const error = new Error(message);
+  error.name = "HandoffAcceptanceError";
+  error.code = code;
+  return error;
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+export function resolveHandoffAcceptance(input = {}, legacyHandoff) {
+  const projection = Array.isArray(input)
+    ? { events: input, handoff: legacyHandoff }
+    : input;
+  const {
+    events = [],
+    handoff,
+    ledgerValid = true,
+    ledgerErrors = [],
+  } = projection ?? {};
+
+  if (ledgerValid !== true) {
+    return {
+      status: "INCONSISTENT",
+      reasonCodes: uniqueSorted(ledgerErrors.map((error) => typeof error === "string" ? error : error?.code)),
+    };
+  }
+
+  if (!handoff?.state?.workStateFingerprint) {
+    return { status: "UNBOUND" };
+  }
+
+  const acceptedEvents = (events ?? []).filter(
+    (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoff.handoffId,
+  );
+
+  if (acceptedEvents.length === 0) {
+    return { status: "OPEN" };
+  }
+
+  if (acceptedEvents.length > 1) {
+    return { status: "INCONSISTENT" };
+  }
+
+  const accepted = acceptedEvents[0];
+  if (accepted.details?.handoffDigest !== handoff.artifactDigest) {
+    return { status: "INCONSISTENT" };
+  }
+
+  return {
+    status: "ACCEPTED",
+    consumerId: accepted.details?.consumerId,
+    ...(accepted.details?.harness ? { harness: accepted.details.harness } : {}),
+    acceptedAt: accepted.at,
+  };
+}
+
+export async function readHandoffAcceptanceLedger(target, packageRoot = getPackageRoot(), { taskId } = {}) {
+  try {
+    return await validateEventLedger(target, packageRoot, { taskId });
+  } catch (error) {
+    return {
+      valid: false,
+      events: [],
+      errors: [{
+        code: error.code ?? "E_EVENT_INVALID",
+        message: error.message,
+      }],
+    };
+  }
+}
+
+export async function acceptCanonicalHandoff(target, {
+  taskId,
+  handoffId,
+  consumerId,
+  harness,
+  packageRoot = getPackageRoot(),
+} = {}) {
+  if (!target || typeof target !== "string") {
+    throw acceptanceError("E_TARGET_REQUIRED", "target path is required");
+  }
+  if (!taskId || typeof taskId !== "string") {
+    throw acceptanceError("E_TASK_REQUIRED", "taskId is required");
+  }
+  if (!handoffId || typeof handoffId !== "string") {
+    throw acceptanceError("E_HANDOFF_INVALID", "handoffId is required");
+  }
+
+  const normalizedConsumerId = normalizePortableText(consumerId, {
+    label: "consumerId",
+    maxLength: 128,
+  });
+  assertPortableContextSafe(normalizedConsumerId, { label: "consumerId" });
+
+  const normalizedHarness = harness !== undefined
+    ? normalizePortableText(harness, {
+      label: "harness",
+      maxLength: 64,
+      optional: true,
+    })
+    : null;
+  if (normalizedHarness) {
+    assertPortableContextSafe(normalizedHarness, { label: "harness" });
+  }
+
+  return withTaskTransaction(
+    {
+      target,
+      taskId,
+      packageRoot,
+      operation: "handoff-accept",
+      recordCommitEvent: true,
+    },
+    async () => {
+      const { value: handoff } = await readCanonicalHandoff(target, {
+        taskId,
+        handoffId,
+        packageRoot,
+      });
+
+      if (!handoff.state?.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_UNBOUND,
+          "Handoff snapshot is unbound (lacks state.workStateFingerprint); create a fresh handoff",
+        );
+      }
+
+      const currentState = await readWorkState(target, { packageRoot, taskId });
+      if (!currentState) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Canonical work state is unavailable for handoff acceptance",
+        );
+      }
+
+      const currentWorkStateFingerprint = canonicalFingerprint(currentState);
+      if (currentWorkStateFingerprint !== handoff.state.workStateFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current work state has drifted from handoff workStateFingerprint",
+        );
+      }
+
+      const contract = await readContract(target, packageRoot, { taskId });
+      const route = await readPersistedRoute(target, packageRoot, { taskId });
+      try {
+        assertStateIdentity({ contract, route, state: currentState });
+      } catch (error) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          `Current canonical task artifacts are not coherent with one another: ${error.message}`,
+        );
+      }
+      if (contract.fingerprint !== handoff.state.contractFingerprint) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current contract fingerprint has drifted from handoff contractFingerprint",
+        );
+      }
+      if ((route.fingerprint ?? null) !== (handoff.state.routeFingerprint ?? null)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current route fingerprint has drifted from handoff routeFingerprint",
+        );
+      }
+
+      const repositoryFingerprint = await currentRepositoryFingerprint(target);
+      if (compareRepositoryFingerprint(handoff.state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current repository branch or HEAD has drifted from handoff snapshot",
+        );
+      }
+
+      const changedPaths = await currentChangedPaths(target);
+      const currentList = [...new Set((changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      const handoffList = [...new Set((handoff.state.changedPaths ?? []).map((p) => p.replaceAll("\\", "/")))].sort();
+      if (JSON.stringify(currentList) !== JSON.stringify(handoffList)) {
+        throw acceptanceError(
+          E_HANDOFF_STALE,
+          "Current changed paths have drifted from handoff snapshot",
+        );
+      }
+
+      const ledgerResult = await validateEventLedger(target, packageRoot, { taskId });
+      if (!ledgerResult.valid) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "Task event ledger is invalid",
+        );
+      }
+
+      const events = ledgerResult.events;
+      const createdEvent = events.find(
+        (e) => e.event === "HANDOFF_CREATED" && e.details?.handoffId === handoffId,
+      );
+      if (!createdEvent || createdEvent.details?.digest !== handoff.artifactDigest) {
+        throw acceptanceError(
+          E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+          "No matching HANDOFF_CREATED event with matching digest found in ledger",
+        );
+      }
+
+      const existingAccepted = events.filter(
+        (e) => e.event === "HANDOFF_ACCEPTED" && e.details?.handoffId === handoffId,
+      );
+
+      if (existingAccepted.length > 0) {
+        const prev = existingAccepted[0];
+        if (prev.details?.consumerId === normalizedConsumerId) {
+          return {
+            accepted: true,
+            idempotent: true,
+            handoffId,
+            consumerId: normalizedConsumerId,
+            harness: prev.details?.harness ?? null,
+            acceptedAt: prev.at,
+          };
+        }
+        throw acceptanceError(
+          E_HANDOFF_ALREADY_ACCEPTED,
+          `Handoff ${handoffId} has already been accepted by consumer "${prev.details?.consumerId}"`,
+        );
+      }
+
+      const eventDetails = {
+        handoffId,
+        handoffDigest: handoff.artifactDigest,
+        consumerId: normalizedConsumerId,
+        ...(normalizedHarness ? { harness: normalizedHarness } : {}),
+      };
+
+      const appended = await appendProtocolEvent(
+        target,
+        {
+          taskId,
+          event: "HANDOFF_ACCEPTED",
+          details: eventDetails,
+        },
+        packageRoot,
+        { taskId },
+      );
+
+      return {
+        accepted: true,
+        idempotent: false,
+        handoffId,
+        consumerId: normalizedConsumerId,
+        harness: normalizedHarness ?? null,
+        acceptedAt: appended.at,
+      };
+    },
+  );
+}

package/src/core/handoff.js

@@ -2,12 +2,13 @@ import { randomUUID } from "node:crypto";
 import { readdir } from "node:fs/promises";
 
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
-import { assertSecretFree } from "./receipt.js";
+import { assertPortableContextSafe, normalizePortableText } from "./portable-context.js";
 import { appendProtocolEvent } from "./events.js";
-import { currentChangedPaths } from "./repository.js";
+import { currentChangedPaths, currentRepositoryFingerprint } from "./repository.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { readWorkState } from "./work-state.js";
+import { assertStateIdentity } from "./completion-relationships.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { readContinuity } from "./continuity.js";
 import { getPackageRoot } from "./templates.js";
@@ -26,12 +27,13 @@ function handoffError(code, message, artifacts = []) {
   return error;
 }
 
-function optionalText(value, label) {
+function optionalText(value, label, maxLength = 2000) {
   if (value === undefined || value === null) return null;
-  if (typeof value !== "string" || value.trim() === "") {
+  try {
+    return normalizePortableText(value, { label, maxLength, optional: true });
+  } catch (error) {
     throw handoffError("E_HANDOFF_INVALID", `${label} must be a non-empty string when provided`);
   }
-  return value;
 }
 
 function pathList(value) {
@@ -43,8 +45,22 @@ function handoffWithoutDigest(value) {
   return body;
 }
 
+export function compareRepositoryFingerprint(expected, current) {
+  const expectedUnavailable = !expected || (expected.branch === null && expected.head === null);
+  const currentUnavailable = !current || (current.branch === null && current.head === null);
+  if (expectedUnavailable && currentUnavailable) return "NOT_VERIFIED";
+  if (expectedUnavailable !== currentUnavailable) return "MISMATCH";
+  return expected.branch === current.branch && expected.head === current.head
+    ? "MATCH"
+    : "MISMATCH";
+}
+
 export function validateHandoffDigest(handoff) {
-  assertSecretFree(handoff);
+  try {
+    assertPortableContextSafe(handoff);
+  } catch (error) {
+    throw handoffError("E_HANDOFF_INVALID", error.message);
+  }
   if (typeof handoff?.artifactDigest !== "string"
     || handoff.artifactDigest !== canonicalFingerprint(handoffWithoutDigest(handoff))) {
     throw handoffError("E_HANDOFF_TAMPERED", "Handoff artifact digest does not match its canonical content");
@@ -73,17 +89,33 @@ export async function buildCanonicalHandoff(target, {
   createdAt = new Date().toISOString(),
 } = {}) {
   if (!taskId) throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "taskId is required to build a handoff");
-  const [state, contract, route, claims, changedPaths, continuity] = await Promise.all([
+  const [state, contract, route, claims, changedPaths, continuity, repositoryFingerprint] = await Promise.all([
     readWorkState(target, { packageRoot, taskId }),
     readContract(target, packageRoot, { taskId }),
     readPersistedRoute(target, packageRoot, { taskId }),
     resolveTaskClaimState(target, { packageRoot, taskId }),
     currentChangedPaths(target),
     currentContinuity(target, packageRoot, taskId),
+    currentRepositoryFingerprint(target),
   ]);
   if (!state || !contract || !route || changedPaths === null || !claims.valid) {
     throw handoffError("E_HANDOFF_STATE_UNAVAILABLE", "Canonical task state, route, claims, and changed paths are required for a handoff");
   }
+  try {
+    assertStateIdentity({ contract, route, state });
+  } catch (error) {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      `Canonical task artifacts are not coherent for handoff creation: ${error.message}`,
+      error.artifacts ?? [],
+    );
+  }
+  if (compareRepositoryFingerprint(state.repositoryFingerprint, repositoryFingerprint) === "MISMATCH") {
+    throw handoffError(
+      "E_HANDOFF_STATE_UNAVAILABLE",
+      "Canonical repository fingerprint has drifted from current repository state",
+    );
+  }
   const checkItems = [...(state.checks ?? [])];
   const executionRefs = pathList(checkItems.map((check) => check.executionRef).filter(Boolean));
   const checkIds = pathList(checkItems.map((check) => check.id).filter(Boolean));
@@ -101,9 +133,10 @@ export async function buildCanonicalHandoff(target, {
       phase: WORK_PHASES.includes(state.phase) ? state.phase : "UNKNOWN",
       revision: state.revision ?? 0,
       verificationCycle: state.verificationCycle ?? 1,
+      workStateFingerprint: canonicalFingerprint(state),
       contractFingerprint: contract.fingerprint,
       routeFingerprint: route.fingerprint ?? null,
-      repositoryFingerprint: state.repositoryFingerprint ?? { branch: null, head: null },
+      repositoryFingerprint,
       writeClaims: pathList(claims.effectiveWriteClaims ?? []),
       changedPaths: pathList(changedPaths),
     },

package/src/core/inspect.js

@@ -15,6 +15,8 @@ import { findTaskById } from "./task-discovery.js";
 import { buildTaskTrace } from "./trace.js";
 import { evaluateProgress } from "./progress.js";
 import { readEvents } from "./events.js";
+import { taskStructuralQualityDirectory } from "./task-paths.js";
+import { projectStructuralQualityStatus } from "./structural-quality/status.js";
 
 function reasonCodesFor({ state, trace, progress }) {
   const codes = [];
@@ -28,6 +30,40 @@ function reasonCodesFor({ state, trace, progress }) {
   return codes;
 }
 
+function structuralQualityIssues(quality, taskId) {
+  if (!quality || quality.mode !== "gate") return [];
+  const qualityPath = quality.current?.artifactRef ?? taskStructuralQualityDirectory(taskId);
+  if (quality.baseline?.status !== "OBSERVED") {
+    return [{
+      code: "E_STRUCTURAL_QUALITY_BASELINE_MISSING",
+      message: "Structural-quality gate evidence has no valid immutable baseline.",
+      path: taskStructuralQualityDirectory(taskId),
+    }];
+  }
+  if (!quality.current?.artifactRef) {
+    return [{
+      code: "E_STRUCTURAL_QUALITY_EVIDENCE_STALE",
+      message: "Structural-quality gate has no evaluation for the current verification cycle.",
+      path: qualityPath,
+    }];
+  }
+  if (quality.current.status === "FAIL") {
+    return [{
+      code: "E_STRUCTURAL_QUALITY_REGRESSION",
+      message: "Structural-quality verification detected a regression.",
+      path: qualityPath,
+    }];
+  }
+  if (quality.current.status === "BLOCKED") {
+    return [{
+      code: "E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE",
+      message: "Structural-quality verification is blocked or incomparable.",
+      path: qualityPath,
+    }];
+  }
+  return [];
+}
+
 async function buildTaskInspection({ target, packageRoot, taskId, state, classifiedStatus = null }) {
   const trace = await buildTaskTrace({ target, packageRoot, taskId });
   const events = await readEvents(target, packageRoot, { taskId });
@@ -39,6 +75,22 @@ async function buildTaskInspection({ target, packageRoot, taskId, state, classif
   )].sort();
 
   const issues = [];
+  let structuralQuality;
+  try {
+    structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId });
+  } catch (error) {
+    structuralQuality = {
+      mode: "off",
+      provider: null,
+      baseline: { status: "INVALID", qualitySignal: null, artifactRef: null, fingerprint: null },
+      current: { status: "NOT_OBSERVED", verificationCycle: null, attempt: null, qualitySignal: null, delta: null, bottleneck: null, artifactRef: null },
+      comparable: null,
+      completionRequired: false,
+      reasonCodes: [error.code ?? "E_STRUCTURAL_QUALITY_EVIDENCE_STALE"],
+      next: null,
+    };
+  }
+  issues.push(...structuralQualityIssues(structuralQuality, taskId));
   if (!trace.snapshot.consistent) {
     issues.push({ code: "E_TRACE_SNAPSHOT_INCONSISTENT", message: "Task artifacts changed while being read; rerun inspect for a consistent view." });
   }
@@ -98,6 +150,7 @@ async function buildTaskInspection({ target, packageRoot, taskId, state, classif
       valid: trace.integrity.valid,
       errors: trace.integrity.errors,
     },
+    structuralQuality,
     audit: {},
     completion: {},
     issues,
@@ -213,6 +266,17 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const taskInspection = taskId
     ? await buildTaskInspection({ target, packageRoot, taskId, state: rawState, classifiedStatus: classifiedState.status })
     : null;
+  for (const issue of taskInspection?.issues ?? []) {
+    if (!issue.code.startsWith("E_STRUCTURAL_QUALITY")) continue;
+    findings.push({
+      code: issue.code,
+      severity: "error",
+      path: issue.path,
+      message: issue.message,
+      remediation: `Run forgeloop next --task ${taskId} --json and follow the structural-quality guidance.`,
+      evidence: createEvidence({ kind: "BLOCKED", source: issue.path, result: issue.code }),
+    });
+  }
   return {
     target: { path: target },
     authority: trustedAuthorityConfiguration({ target, authorityContext, runtimeContext }),

package/src/core/integration-invocation-policy.js

@@ -32,6 +32,7 @@ const READ_ONLY_COMMANDS = Object.freeze(new Set([
   "efficiency",
   "workspace-status", "handoff-list", "handoff-show", "responsibility-status",
   "attestation-verify", "attestation-status", "attestation-verify-range",
+  "quality-status",
 ]));
 
 const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
@@ -41,7 +42,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "record-terminal-result", "complete",
   "record-intervention", "record-hypothesis-disposition",
   "usage-record",
-  "workspace-bind", "handoff-create", "responsibility-set", "verify-scope", "attestation-create",
+  "workspace-bind", "handoff-create", "handoff-accept", "responsibility-set", "verify-scope", "attestation-create",
 ]));
 
 const STATIC_RISK_CLASSES = Object.freeze({
@@ -49,6 +50,8 @@ const STATIC_RISK_CLASSES = Object.freeze({
   ...Object.fromEntries([...LOOP_MUTATION_COMMANDS].map((name) => [name, INTEGRATION_RISK_CLASSES.LOOP_MUTATION])),
   "task-resume": INTEGRATION_RISK_CLASSES.CLAIM_REACQUISITION,
   "run-check": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "quality-baseline": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
+  "quality-verify": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
   "run-action": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
   "reconcile-closure": INTEGRATION_RISK_CLASSES.EXTERNAL_EXECUTION,
   "action-propose": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
@@ -186,10 +189,27 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         explicitRebinding: false,
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,
@@ -203,6 +223,17 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         modes: ["AUTO", "CHANGED", "CLAIMED", "FULL"],
         impactedMode: false,
       },
+      structuralQuality: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+        providerNeutral: true,
+        modes: ["off", "observe", "gate"],
+        builtInProviders: ["sentrux"],
+        commands: ["quality-baseline", "quality-verify", "quality-status"],
+        baselineImmutableAfterExecution: true,
+        maxOutputBytes: 2 * 1024 * 1024,
+      },
       codeAttestation: {
         version: 1,
         supported: true,
@@ -232,6 +263,7 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
       { name: "task/responsibility", scope: "TASK" },
       { name: "task/verification-scope", scope: "TASK" },
       { name: "task/attestation", scope: "TASK" },
+      { name: "task/structural-quality", scope: "TASK" },
       { name: "task/actions", scope: "TASK" },
       { name: "task/action", scope: "TASK" },
       { name: "task/approvals", scope: "TASK" },

package/src/core/integration-resources.js

@@ -14,10 +14,12 @@ import { readJsonArtifact } from "./artifacts.js";
 import { taskDirectory } from "./task-paths.js";
 import { resolveWorkspaceBindingStatus } from "./workspace-binding.js";
 import { listCanonicalHandoffs } from "./handoff.js";
+import { readHandoffAcceptanceLedger, resolveHandoffAcceptance } from "./handoff-acceptance.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
 import { buildExecutionProfileContext } from "./execution-profile-context.js";
+import { projectStructuralQualityStatus } from "./structural-quality/service.js";
 
 /**
  * Canonical integration resource allowlist.
@@ -77,6 +79,7 @@ export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
     scope: "TASK",
     description: "Local code-attestation status and trust level for one task.",
   }),
+  "task/structural-quality": Object.freeze({ scope: "TASK", description: "Read-only structural-quality baseline, evaluation, comparison, and next-action projection." }),
   "task/actions": Object.freeze({ scope: "TASK", description: "Canonical durable action summaries for one task." }),
   "task/action": Object.freeze({ scope: "TASK", description: "One canonical durable action artifact." }),
   "task/approvals": Object.freeze({ scope: "TASK", description: "Durable approval artifacts for one task." }),
@@ -157,6 +160,14 @@ export async function readForgeLoopIntegrationResource(uri, {
       }
       break;
     }
+    case "task/structural-quality": {
+      if (typeof taskId !== "string" || !taskId) {
+        const error = new Error(`Resource ${uri} requires a taskId`);
+        error.code = "E_TASK_REQUIRED";
+        throw error;
+      }
+      break;
+    }
     case "task/actions":
     case "task/action":
     case "task/approvals":
@@ -174,12 +185,38 @@ export async function readForgeLoopIntegrationResource(uri, {
     const projection = await resolveTaskClaimState(projectPath, { taskId, packageRoot });
     return { uri, taskId, data: ownershipProjection(projection) };
   }
+  if (uri === "task/structural-quality") {
+    return {
+      uri,
+      taskId,
+      data: await projectStructuralQualityStatus({ projectRoot: projectPath, target: projectPath, packageRoot, taskId }),
+    };
+  }
   if (uri === "task/workspace-binding") {
     return { uri, taskId, data: await resolveWorkspaceBindingStatus(projectPath, { packageRoot, taskId }) };
   }
   if (uri === "task/handoffs") {
     const handoffs = await listCanonicalHandoffs(projectPath, { packageRoot, taskId });
-    return { uri, taskId, data: { taskId, count: handoffs.length, handoffs } };
+    const ledger = await readHandoffAcceptanceLedger(projectPath, packageRoot, { taskId });
+    const projectedHandoffs = handoffs.map((handoff) => {
+      const resolved = resolveHandoffAcceptance({
+        events: ledger.events,
+        handoff,
+        ledgerValid: ledger.valid,
+        ledgerErrors: ledger.errors,
+      });
+      return {
+        ...handoff,
+        acceptance: {
+          status: resolved.status,
+          consumerId: resolved.consumerId ?? null,
+          harness: resolved.harness ?? null,
+          acceptedAt: resolved.acceptedAt ?? null,
+          ...(resolved.reasonCodes ? { reasonCodes: [...resolved.reasonCodes] } : {}),
+        },
+      };
+    });
+    return { uri, taskId, data: { taskId, count: projectedHandoffs.length, handoffs: projectedHandoffs } };
   }
   if (uri === "task/responsibility") {
     return { uri, taskId, data: await resolveResponsibilityStatus(projectPath, { packageRoot, taskId }) };

package/src/core/next-action-model.js

@@ -12,6 +12,10 @@ export const NEXT_ACTIONS = Object.freeze({
   ENTER_VERIFYING: "ENTER_VERIFYING",
   CONTINUE_IMPLEMENTATION: "CONTINUE_IMPLEMENTATION",
   RECORD_VERIFICATION: "RECORD_VERIFICATION",
+  CAPTURE_STRUCTURAL_QUALITY_BASELINE: "CAPTURE_STRUCTURAL_QUALITY_BASELINE",
+  VERIFY_STRUCTURAL_QUALITY: "VERIFY_STRUCTURAL_QUALITY",
+  DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION: "DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION",
+  RESOLVE_STRUCTURAL_QUALITY_BLOCKER: "RESOLVE_STRUCTURAL_QUALITY_BLOCKER",
   DIAGNOSE: "DIAGNOSE",
   RECORD_DIAGNOSIS: "RECORD_DIAGNOSIS",
   CORRECT: "CORRECT",
@@ -118,6 +122,7 @@ export function result({
   approvalRequired = undefined,
   capabilityDecision = undefined,
   reconciliationAuthorityRequired = undefined,
+  optionalActions = undefined,
 }) {
   const normalizedReasons = reasons
     .map((reason) => {
@@ -158,6 +163,7 @@ export function result({
     ...(reconciliationAuthorityRequired
       ? { reconciliationAuthorityRequired: structuredClone(reconciliationAuthorityRequired) }
       : {}),
+    ...(optionalActions?.length ? { optionalActions: structuredClone(optionalActions) } : {}),
   };
 }
 
@@ -167,6 +173,9 @@ export function commandFor(action) {
     [NEXT_ACTIONS.RUN_PREFLIGHT]: "forgeloop preflight --json",
     [NEXT_ACTIONS.START_EXECUTION]: "forgeloop advance --to EXECUTING",
     [NEXT_ACTIONS.ENTER_VERIFYING]: "forgeloop advance --to VERIFYING",
+    [NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE]: "forgeloop quality-baseline --task <id> --json",
+    [NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY]: "forgeloop quality-verify --task <id> --json",
+    [NEXT_ACTIONS.DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION]: "forgeloop advance --to DIAGNOSING",
     [NEXT_ACTIONS.DIAGNOSE]: "forgeloop advance --to DIAGNOSING",
     [NEXT_ACTIONS.CORRECT]: "forgeloop advance --to CORRECTING",
     [NEXT_ACTIONS.ENTER_REVIEWING]: "forgeloop advance --to REVIEWING",
@@ -237,7 +246,7 @@ export function recordTerminalResultCommandSpec(requirement) {
   };
 }
 
-export function decision(input, action, reason, requiredArtifacts = [], missingArtifacts = []) {
+export function decision(input, action, reason, requiredArtifacts = [], missingArtifacts = [], optionalActions = undefined) {
   const command = commandFor(action);
   return result({
     ...input,
@@ -246,6 +255,7 @@ export function decision(input, action, reason, requiredArtifacts = [], missingA
     ...(command ? { commands: [command] } : {}),
     requiredArtifacts,
     missingArtifacts,
+    optionalActions,
   });
 }