@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/src/core/advisory-context/service.js

@@ -0,0 +1,140 @@
+import path from "node:path";
+
+import {
+  normalizePortableText,
+  assertPortableContextSafe,
+} from "../portable-context.js";
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  normalizeAdvisoryRecallOptions,
+} from "./constants.js";
+import {
+  normalizeAdvisoryContextResult,
+  resolveAdvisoryContextProvider,
+} from "./provider.js";
+import {
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_QUERY_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+  E_PORTABLE_CONTEXT_INVALID,
+} from "../error-codes.js";
+
+function serviceError(code, message, cause) {
+  const error = new Error(message, cause !== undefined ? { cause } : undefined);
+  error.name = "AdvisoryContextServiceError";
+  error.code = code;
+  return error;
+}
+
+export async function recallAdvisoryContext({
+  target,
+  taskId,
+  providerName,
+  query,
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+  runtimeContext,
+} = {}) {
+  if (!target || typeof target !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "Target project path is required for advisory recall",
+    );
+  }
+
+  if (!taskId || typeof taskId !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "taskId is required for advisory recall",
+    );
+  }
+
+  if (!providerName || typeof providerName !== "string") {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      "providerName is required for advisory recall",
+    );
+  }
+
+  let normalizedQuery;
+  try {
+    normalizedQuery = normalizePortableText(query, {
+      label: "advisory query",
+      maxLength: ADVISORY_CONTEXT_LIMITS.maxQueryChars,
+    });
+    assertPortableContextSafe(normalizedQuery, { label: "advisory query" });
+  } catch (err) {
+    if (err.code === E_PORTABLE_CONTEXT_INVALID) {
+      throw err;
+    }
+    throw serviceError(
+      E_ADVISORY_CONTEXT_QUERY_INVALID,
+      `Advisory context query is invalid: ${err.message}`,
+      err,
+    );
+  }
+
+  const effectiveOptions = normalizeAdvisoryRecallOptions({
+    limit,
+    maxItemChars,
+    maxTotalChars,
+    timeoutMs,
+  });
+
+  let provider;
+  try {
+    provider = await resolveAdvisoryContextProvider({
+      providers: runtimeContext?.advisoryContextProviders,
+      providerName,
+    });
+  } catch (err) {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+      `Advisory context provider "${providerName}" failed validation: ${err.message}`,
+      err,
+    );
+  }
+
+  if (!provider) {
+    throw serviceError(
+      E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+      `Advisory context provider "${providerName}" is not registered in runtime context`,
+    );
+  }
+
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        serviceError(
+          E_ADVISORY_CONTEXT_TIMEOUT,
+          `Advisory recall from provider "${providerName}" timed out after ${effectiveOptions.timeoutMs}ms`,
+        ),
+      );
+    }, effectiveOptions.timeoutMs);
+  });
+
+  let rawResult;
+  try {
+    const recallPromise = Promise.resolve(
+      provider.recall({
+        projectPath: path.resolve(target),
+        taskId,
+        query: normalizedQuery,
+        ...effectiveOptions,
+      }),
+    );
+    rawResult = await Promise.race([recallPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  return normalizeAdvisoryContextResult(rawResult, {
+    provider,
+    taskId,
+    ...effectiveOptions,
+  });
+}

package/src/core/artifact-registry.js

@@ -283,6 +283,18 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Immutable trajectory evaluation results compiled from the canonical trace against a local reference scenario.",
   }),
+  structuralQuality: Object.freeze({
+    key: "structuralQuality",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.structuralQuality}/baseline.json`,
+    schema: "structural-quality",
+    owner: "PROTOCOL_COMPILED",
+    mutability: "BASELINE_IMMUTABLE_AFTER_EXECUTION",
+    trustRole: "STRUCTURAL_QUALITY_EVIDENCE",
+    isPublic: true,
+    isPersisted: true,
+    description: "Typed, provider-neutral structural-quality baseline and evaluation evidence bound to task, route, policy, scope, and provider identity.",
+  }),
   usage: Object.freeze({
     key: "usage",
     scope: "TASK",

package/src/core/audit.js

@@ -11,6 +11,7 @@ import { validateActionLedgerConsistency } from "./actions.js";
 import { readCodeManifest } from "./code-manifest.js";
 import { readAttestationStatement, validateAttestationStatement } from "./attestation.js";
 import { assertAttestationStatementBindings, verifyCodeManifestContent } from "./attestation-verifier.js";
+import { projectStructuralQualityStatus } from "./structural-quality/status.js";
 
 function sortErrors(errors) {
   return [...errors].sort((left, right) => left.code.localeCompare(right.code)
@@ -244,6 +245,33 @@ export async function evaluateAudit({
     policyStatus = { status: "NOT_APPLICABLE", provenRules: 0, inertRules: 0, unsupportedRules: 0, baselineViolations: 0, drift: false };
   }
 
+  let structuralQuality = {
+    mode: "off",
+    provider: null,
+    baseline: { status: "NOT_REQUESTED", 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: [],
+    next: null,
+  };
+  if (taskId) {
+    try {
+      structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId });
+    } catch (error) {
+      structuralQuality = {
+        ...structuralQuality,
+        mode: "unknown",
+        reasonCodes: [error.code ?? "E_STRUCTURAL_QUALITY_EVIDENCE_STALE"],
+      };
+    }
+  }
+  const qualityEvidenceKind = structuralQuality.current.status === "PASS" || structuralQuality.current.status === "FAIL"
+    ? "OBSERVED"
+    : structuralQuality.current.status === "BLOCKED" || (structuralQuality.mode === "gate" && structuralQuality.baseline.status !== "OBSERVED")
+      ? "BLOCKED"
+      : structuralQuality.mode === "off" ? "NOT_REQUESTED" : "NOT_VERIFIED";
+
   return {
     schemaVersion: 1,
     protocolVersion: PROTOCOL_VERSION,
@@ -256,6 +284,15 @@ export async function evaluateAudit({
       manifest: Boolean(manifest),
     },
     policy: policyStatus,
+    structuralQuality: {
+      ...structuralQuality,
+      policy: structuralQuality.mode === "off" ? null : {
+        mode: structuralQuality.mode,
+        provider: structuralQuality.provider,
+        result: structuralQuality.current.status,
+      },
+      evidenceKind: qualityEvidenceKind,
+    },
     completion,
     attestation: {
       mode: attestation.mode,
@@ -282,6 +319,7 @@ export async function evaluateAudit({
       route: routeRel,
       state: stateRel,
       receipt: receiptRel,
+      structuralQuality: taskId ? taskArtifactPath(taskId, "structuralQuality") : null,
     },
   };
 }

package/src/core/bundles.js

@@ -8,7 +8,7 @@ import { validateChecksExecutionProvenance } from "./completion-artifacts.js";
 import { readExecutionArtifact } from "./execution.js";
 import { assertContinuitySemantics } from "./continuity.js";
 import { validateEventLedger } from "./events.js";
-import { taskArtifactPath, taskDirectory } from "./task-paths.js";
+import { taskArtifactPath, taskDirectory, taskStructuralQualityDirectory } from "./task-paths.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { E_TASK_CLAIM_OWNERSHIP_INCONSISTENT } from "./error-codes.js";
 import { listActions } from "./actions.js";
@@ -19,6 +19,13 @@ import { validateWorkspaceBinding } from "./workspace-binding.js";
 import { validateCodeManifest, validateCodeManifestBindings } from "./code-manifest.js";
 import { assertAttestationStatementBindings } from "./attestation-verifier.js";
 import { validateAttestationStatement } from "./attestation.js";
+import {
+  listStructuralQualityEvaluations,
+  readStructuralQualityBaseline,
+  validateStructuralQualityArtifact,
+  validateStructuralQualityBindings,
+} from "./structural-quality/artifacts.js";
+import { normalizeStructuralQualityConfig, structuralQualityPolicyFingerprint } from "./structural-quality/policy.js";
 
 export const BUNDLE_SCHEMA_VERSION = 1;
 const BUNDLE_ROOT = ".forgeloop/tasks";
@@ -42,6 +49,96 @@ function bundleBindingError(code, message) {
   return error;
 }
 
+function structuralQualityBundleKind(artifact) {
+  if (artifact === "structural-quality/baseline.json") return "baseline";
+  if (/^structural-quality\/evaluations\/cycle-\d+-attempt-\d+\.json$/u.test(artifact)) return "evaluation";
+  if (artifact.startsWith("structural-quality/")) {
+    throw bundleBindingError("E_BUNDLE_PATH_INVALID", `Unknown structural-quality bundle artifact: ${artifact}`);
+  }
+  return null;
+}
+
+function bundleQualityReference(reference, taskId) {
+  if (typeof reference !== "string" || reference.trim() === "") {
+    throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "Structural-quality check has no artifact reference");
+  }
+  const normalized = reference.replaceAll("\\", "/");
+  const sourceRoot = taskStructuralQualityDirectory(taskId).replaceAll("\\", "/");
+  const suffix = normalized.startsWith(`${sourceRoot}/`)
+    ? normalized.slice(sourceRoot.length + 1)
+    : normalized.startsWith("structural-quality/")
+      ? normalized.slice("structural-quality/".length)
+      : null;
+  if (!suffix || !(suffix === "baseline.json" || /^evaluations\/cycle-\d+-attempt-\d+\.json$/u.test(suffix))) {
+    throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "Structural-quality artifact reference escapes its task quality directory");
+  }
+  return `structural-quality/${suffix}`;
+}
+
+function structuralQualityCheckProjection(value) {
+  if (value.status === "PASS") return { status: "passed", evidenceKind: "OBSERVED" };
+  if (value.status === "FAIL") return { status: "failed", evidenceKind: "OBSERVED" };
+  if (value.status === "BLOCKED") return { status: "blocked", evidenceKind: "BLOCKED" };
+  return { status: "not-run", evidenceKind: "NOT_VERIFIED" };
+}
+
+function assertStructuralQualityBundleEvidence({ loaded, manifest, taskId }) {
+  const quality = loaded.structuralQuality;
+  if (!quality) return;
+  const baseline = quality.baseline;
+  const evaluations = quality.evaluations ?? [];
+  const qualityArtifacts = new Map();
+  if (baseline) qualityArtifacts.set("structural-quality/baseline.json", baseline);
+  for (const evaluation of evaluations) {
+    const name = `structural-quality/evaluations/cycle-${evaluation.verificationCycle}-attempt-${evaluation.attempt}.json`;
+    qualityArtifacts.set(name, evaluation);
+  }
+  for (const value of [baseline, ...evaluations].filter(Boolean)) {
+    if (value.taskId !== taskId) throw bundleBindingError("E_BUNDLE_TASK_MISMATCH", "Structural-quality artifact taskId does not match its bundle task");
+    const bindingErrors = validateStructuralQualityBindings(value);
+    if (bindingErrors.length > 0) throw bundleBindingError(bindingErrors[0].code, bindingErrors[0].message);
+  }
+  const baselineFingerprint = baseline ? canonicalFingerprint(baseline) : null;
+  const bundledConfig = loaded.config?.structuralQuality;
+  let policy = null;
+  if (bundledConfig) policy = normalizeStructuralQualityConfig(bundledConfig);
+  const expectedContractFingerprint = loaded.contract ? canonicalFingerprint(loaded.contract) : null;
+  const expectedRouteFingerprint = loaded.route ? canonicalFingerprint(loaded.route) : null;
+  for (const value of [baseline, ...evaluations].filter(Boolean)) {
+    if (baselineFingerprint && value.role === "EVALUATION" && value.bindings?.baselineFingerprint !== baselineFingerprint) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH", "Structural-quality evaluation does not bind the bundled baseline");
+    }
+    if (policy && value.bindings?.policyFingerprint !== structuralQualityPolicyFingerprint(policy)) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH", "Structural-quality artifact policy binding does not match bundled configuration");
+    }
+    if (expectedContractFingerprint && value.bindings?.contractFingerprint !== expectedContractFingerprint) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH", "Structural-quality contract binding does not match the bundled contract");
+    }
+    if (expectedRouteFingerprint && value.bindings?.routeFingerprint !== expectedRouteFingerprint) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH", "Structural-quality route binding does not match the bundled route");
+    }
+  }
+  const checks = [
+    ...(loaded.state?.checks ?? []),
+    ...(loaded.receipt?.checks ?? []),
+  ].filter((check) => check?.kind === "structural-quality");
+  for (const check of checks) {
+    const bundleReference = bundleQualityReference(check.details?.artifactRef, taskId);
+    const value = qualityArtifacts.get(bundleReference);
+    if (!value) throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", `Bundled structural-quality check references missing ${bundleReference}`);
+    if (check.details?.artifactFingerprint !== canonicalFingerprint(value)) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", `Bundled structural-quality check fingerprint does not match ${bundleReference}`);
+    }
+    const expected = structuralQualityCheckProjection(value);
+    if (check.status !== expected.status || check.evidenceKind !== expected.evidenceKind) {
+      throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", `Bundled structural-quality check does not match ${bundleReference}`);
+    }
+  }
+  for (const artifact of manifest.artifacts.filter((item) => item.startsWith("structural-quality/"))) {
+    if (!qualityArtifacts.has(artifact)) throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", `Bundled structural-quality manifest entry was not loaded: ${artifact}`);
+  }
+}
+
 function assertBundledCodeManifestBindings({ loaded, ledger, taskId }) {
   const manifest = loaded.codeManifest;
   if (!manifest) return;
@@ -191,6 +288,22 @@ export async function exportTaskBundle(target, taskId, packageRoot) {
     if (destinationName === "verification-scope.json") exportedVerificationScope = copied;
   }
 
+  // Structural-quality evidence is provider output made portable by
+  // ForgeLoop. Copy typed artifacts rather than raw process output, and keep
+  // every immutable evaluation so an audit can inspect the complete attempt
+  // history without rescanning the project.
+  const qualityBaseline = await readStructuralQualityBaseline(target, taskId, packageRoot);
+  const qualityEvaluations = await listStructuralQualityEvaluations(target, taskId, packageRoot);
+  if (qualityBaseline) {
+    await writeJsonArtifact(target, `${directory}/structural-quality/baseline.json`, qualityBaseline.value, "structural-quality", packageRoot);
+    artifacts.push("structural-quality/baseline.json");
+  }
+  for (const evaluation of qualityEvaluations) {
+    const destination = `structural-quality/evaluations/cycle-${evaluation.value.verificationCycle}-attempt-${evaluation.value.attempt}.json`;
+    await writeJsonArtifact(target, `${directory}/${destination}`, evaluation.value, "structural-quality", packageRoot);
+    artifacts.push(destination);
+  }
+
   if (exportedWorkspaceBinding?.value) {
     exportedWorkspaceBinding.value = await validateWorkspaceBinding(exportedWorkspaceBinding.value, packageRoot);
     if (exportedWorkspaceBinding.value.taskId !== taskId) {
@@ -335,6 +448,22 @@ export async function readTaskBundle(target, taskId, packageRoot) {
   };
   const executions = {};
   for (const artifact of manifest.value.artifacts) {
+    const qualityKind = structuralQualityBundleKind(artifact);
+    if (qualityKind) {
+      const qualityArtifact = await readJsonArtifact(target, `${directory}/${artifact}`, "structural-quality", packageRoot);
+      validateStructuralQualityArtifact(qualityArtifact.value, artifact);
+      if (qualityArtifact.value.taskId !== taskId) {
+        throw bundleBindingError("E_BUNDLE_TASK_MISMATCH", `Structural-quality ${qualityKind} taskId does not match its bundle task`);
+      }
+      loaded.structuralQuality ??= { baseline: null, evaluations: [] };
+      if (qualityKind === "baseline") {
+        if (loaded.structuralQuality.baseline) throw bundleBindingError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "A bundle cannot contain more than one structural-quality baseline");
+        loaded.structuralQuality.baseline = qualityArtifact.value;
+      } else {
+        loaded.structuralQuality.evaluations.push(qualityArtifact.value);
+      }
+      continue;
+    }
     if (artifact.startsWith("executions/") && artifact.endsWith(".json")) {
       const execution = await readJsonArtifact(target, `${directory}/${artifact}`, "execution", packageRoot);
       executions[execution.value.executionId] = execution.value;
@@ -415,6 +544,10 @@ export async function readTaskBundle(target, taskId, packageRoot) {
     }
     loaded[mapping[0]] = loadedArtifact.value;
   }
+  if (loaded.structuralQuality) {
+    loaded.structuralQuality.evaluations.sort((left, right) => left.verificationCycle - right.verificationCycle || left.attempt - right.attempt);
+    assertStructuralQualityBundleEvidence({ loaded, manifest: manifest.value, taskId });
+  }
   const bundledLedger = loaded.codeManifest && manifest.value.artifacts.includes("events.ndjson")
     ? await validateEventLedger(target, packageRoot, { taskId, eventsPath: `${directory}/events.ndjson` })
     : null;

package/src/core/cli-command-definitions.js

@@ -162,6 +162,51 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Evaluates pre-implementation contract, routing, and gates; synchronizes work state when READY.",
   }),
+  "quality-baseline": Object.freeze({
+    name: "quality-baseline",
+    category: "verification",
+    mutation: "EXTERNAL_EXECUTION",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--replace": Object.freeze({ targetKey: "replace", parseType: "boolean", takesValue: false, description: "replace a different baseline before EXECUTING" }),
+      "--timeout-ms": Object.freeze({ targetKey: "timeoutMs", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--timeout-ms requires a non-negative integer", description: "bounded analyzer timeout in milliseconds" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit baseline result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/structural-quality/baseline.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Captures an immutable provider-neutral structural-quality baseline through the trusted analyzer adapter.",
+  }),
+  "quality-verify": Object.freeze({
+    name: "quality-verify",
+    category: "verification",
+    mutation: "EXTERNAL_EXECUTION",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--timeout-ms": Object.freeze({ targetKey: "timeoutMs", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--timeout-ms requires a non-negative integer", description: "bounded analyzer timeout in milliseconds" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structural-quality verification as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/structural-quality/evaluations/cycle-<n>-attempt-<n>.json", ".forgeloop/task-state/<taskKey>/work-state.json", ".forgeloop/task-state/<taskKey>/execution-receipt.json", ".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Captures one bounded structural-quality evaluation and projects it into canonical verification evidence.",
+  }),
+  "quality-status": Object.freeze({
+    name: "quality-status",
+    category: "verification",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit persisted structural-quality status as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Projects persisted structural-quality baseline and evaluation status without invoking a provider.",
+  }),
   advance: Object.freeze({
     name: "advance",
     category: "lifecycle",
@@ -1127,6 +1172,23 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     mayExecuteExternalProcess: false,
     description: "Reads and verifies one immutable handoff snapshot.",
   }),
+  "handoff-accept": Object.freeze({
+    name: "handoff-accept",
+    category: "task",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      ...CLI_TASK_OPTION,
+      "--handoff": Object.freeze({ targetKey: "handoffId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--handoff requires a handoff ID", description: "handoff identifier" }),
+      "--consumer-id": Object.freeze({ targetKey: "consumerId", parseType: "string", takesValue: true, valueName: "id", missingValueMessage: "--consumer-id requires a consumer ID", description: "consumer identifier accepting the handoff" }),
+      "--harness": Object.freeze({ targetKey: "harness", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--harness requires a harness name", description: "optional harness accepting the handoff" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit acceptance result as JSON" }),
+    }),
+    writes: [".forgeloop/task-state/<taskKey>/events.ndjson"],
+    removes: [],
+    mayExecuteExternalProcess: false,
+    description: "Accepts an immutable handoff exactly once in the task event ledger.",
+  }),
   "responsibility-set": Object.freeze({
     name: "responsibility-set",
     category: "scope",

package/src/core/command-executors.js

@@ -11,6 +11,9 @@ import { runUpdate } from "../commands/update.js";
 import { runActivate } from "../commands/activate.js";
 import { runAdvance } from "../commands/advance.js";
 import { runPreflight } from "../commands/preflight.js";
+import { runQualityBaseline } from "../commands/quality-baseline.js";
+import { runQualityVerify } from "../commands/quality-verify.js";
+import { runQualityStatus } from "../commands/quality-status.js";
 import { runComplete } from "../commands/complete.js";
 import { runAudit } from "../commands/audit.js";
 import { runReport } from "../commands/report.js";
@@ -70,6 +73,7 @@ import { runWorkspaceStatus } from "../commands/workspace-status.js";
 import { runHandoffCreate } from "../commands/handoff-create.js";
 import { runHandoffList } from "../commands/handoff-list.js";
 import { runHandoffShow } from "../commands/handoff-show.js";
+import { runHandoffAccept } from "../commands/handoff-accept.js";
 import { runResponsibilitySet } from "../commands/responsibility-set.js";
 import { runResponsibilityStatus } from "../commands/responsibility-status.js";
 import { runVerifyScope } from "../commands/verify-scope.js";
@@ -132,6 +136,19 @@ export const COMMAND_EXECUTORS = {
     const result = await runPreflight({ target, packageRoot, strict: options.strict, taskId: options.taskId });
     return { result, exitCode: result.status === "READY" ? 0 : 1 };
   },
+  "quality-baseline": async ({ target, packageRoot, options, runtimeContext }) => {
+    const result = await runQualityBaseline({ target, packageRoot, taskId: options.taskId, replace: options.replace, timeoutMs: options.timeoutMs, runtimeContext });
+    return { result, exitCode: ["CAPTURED", "EXISTING", "REPLACED", "NOT_REQUESTED"].includes(result.status) ? 0 : 1 };
+  },
+  "quality-verify": async ({ target, packageRoot, options, authorityContext, runtimeContext }) => {
+    const result = await runQualityVerify({ target, packageRoot, taskId: options.taskId, timeoutMs: options.timeoutMs, authorityContext, runtimeContext });
+    const status = result.evaluation?.status ?? result.status;
+    return { result, exitCode: ["PASS", "NOT_OBSERVED", "CONVERGED", "NOT_REQUESTED"].includes(status) ? 0 : 1 };
+  },
+  "quality-status": async ({ target, packageRoot, options }) => ({
+    result: await runQualityStatus({ target, packageRoot, taskId: options.taskId }),
+    exitCode: 0,
+  }),
   advance: async ({ target, packageRoot, options, authorityContext, runtimeContext }) => ({
     result: await runAdvance({
       target,
@@ -220,6 +237,17 @@ export const COMMAND_EXECUTORS = {
     result: await runHandoffShow({ target, packageRoot, taskId: options.taskId, handoffId: options.handoffId }),
     exitCode: 0,
   }),
+  "handoff-accept": async ({ target, packageRoot, options }) => ({
+    result: await runHandoffAccept({
+      target,
+      packageRoot,
+      taskId: options.taskId,
+      handoffId: options.handoffId,
+      consumerId: options.consumerId,
+      harness: options.harness,
+    }),
+    exitCode: 0,
+  }),
   "responsibility-set": async ({ target, packageRoot, options }) => ({
     result: await runResponsibilitySet({
       target,

package/src/core/command-input.js

@@ -60,6 +60,7 @@ export function defaultCommandInputValues() {
     checkExecutionRef: null,
     checkProvenance: null,
     timeoutMs: null,
+    replace: false,
     scopeRef: null,
     commandArgv: [],
     checkType: null,
@@ -69,6 +70,8 @@ export function defaultCommandInputValues() {
     recipientHint: null,
     handoffNote: null,
     handoffId: null,
+    consumerId: null,
+    harness: null,
     responsibilityLabel: null,
     responsibilityAllowedPaths: [],
     responsibilityReadOnlyPaths: [],
@@ -130,19 +133,38 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   if (command === "efficiency" && !help && !options.taskId) {
     throw inputError("efficiency requires --task");
   }
+  if (["quality-baseline", "quality-verify", "quality-status"].includes(command) && !help && !options.taskId) {
+    throw inputError(`${command} requires --task`);
+  }
+  if (["quality-baseline", "quality-verify"].includes(command) && !help
+    && options.timeoutMs !== null && options.timeoutMs !== undefined
+    && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 0 || options.timeoutMs > 300000)) {
+    throw inputError(`${command} --timeout-ms must be between 0 and 300000`);
+  }
+  if (command !== "quality-baseline" && options.replace === true) {
+    throw inputError(`--replace is only valid for quality-baseline`);
+  }
   if (command !== "usage-record" && options.usageSource !== undefined && options.usageSource !== "ACTOR_REPORTED") {
     throw inputError(`usageSource is not valid for ${command}`);
   }
   if (options.compact === true && !["next", "task-show"].includes(command)) {
     throw inputError(`compact output is not valid for ${command}`);
   }
-  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
+  if (["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "handoff-accept", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"].includes(command)
     && !options.taskId) {
     throw inputError(`${command} requires --task`);
   }
   if (command === "handoff-show" && !help && !options.handoffId) {
     throw inputError("handoff-show requires --id");
   }
+  if (command === "handoff-accept" && !help) {
+    if (!options.handoffId) {
+      throw inputError("handoff-accept requires --handoff");
+    }
+    if (!options.consumerId) {
+      throw inputError("handoff-accept requires --consumer-id");
+    }
+  }
   if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
     throw inputError("responsibility-set requires --label");
   }

package/src/core/completion-artifacts.js

@@ -25,6 +25,7 @@ import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
 import { assertClaimsCoverChangedPaths } from "./task-scope.js";
 import { discoverTasks } from "./task-discovery.js";
 import { listActions } from "./actions.js";
+import { STRUCTURAL_QUALITY_REQUIREMENT } from "./structural-quality/constants.js";
 
 async function actionReceiptSummary(target, packageRoot, taskId) {
   const actions = await listActions(target, { packageRoot, taskId });
@@ -239,6 +240,7 @@ export async function requiredEvidenceForTarget({
     ...(contract.value.successCriteria ?? []),
     ...guideEvidence,
     ...(config.requiredEvidence ?? []),
+    ...(config.structuralQuality?.mode === "gate" ? [STRUCTURAL_QUALITY_REQUIREMENT] : []),
     ...additionalEvidence,
   ])].sort();
 }

package/src/core/completion.js

@@ -18,6 +18,7 @@ import { readConfig } from "./config.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { createCodeManifest, readCodeManifest, validateCodeManifestBindings, writeCodeManifest } from "./code-manifest.js";
 import { getActiveTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { validateStructuralQualityCheckProvenance } from "./structural-quality/service.js";
 
 async function attestationConfiguration(target, packageRoot, errors) {
   try {
@@ -157,6 +158,26 @@ function repairNext(error) {
       return "Do not execute installation-capable verification commands without explicit scoped installation authority; use local equivalents or record NOT_VERIFIED.";
     case "E_VERIFICATION_TOOL_UNAVAILABLE":
       return "Use an available local verifier, an existing equivalent, or record NOT_VERIFIED if installation was not authorized.";
+    case "E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID":
+      return "Repair structuralQuality configuration in .forgeloop/config.json and rerun preflight.";
+    case "E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE":
+    case "E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID":
+    case "E_STRUCTURAL_QUALITY_SCAN_FAILED":
+    case "E_STRUCTURAL_QUALITY_TIMEOUT":
+    case "E_STRUCTURAL_QUALITY_OUTPUT_LIMIT":
+      return "Restore the trusted structural-quality provider and rerun quality-verify; do not promote an unavailable or malformed scan.";
+    case "E_STRUCTURAL_QUALITY_BASELINE_MISSING":
+      return "Run forgeloop quality-baseline --task <id> while the task is PLANNED, before execution begins.";
+    case "E_STRUCTURAL_QUALITY_BASELINE_EXISTS":
+    case "E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID":
+      return "Keep the original baseline and correct the task against it; baseline replacement is only allowed before EXECUTING.";
+    case "E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH":
+    case "E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE":
+      return "Reconcile provider, version, rules, policy, scope, contract, or route drift, then rerun quality-verify in the active cycle.";
+    case "E_STRUCTURAL_QUALITY_EVIDENCE_STALE":
+      return "Run quality-verify for the current verification cycle and refresh the receipt through the canonical completion pipeline.";
+    case "E_STRUCTURAL_QUALITY_REGRESSION":
+      return "Use the bottleneck and root-cause deltas to record an evidence-backed diagnosis, correct within scope, and verify a new cycle.";
     case "E_NEW_POLICY_VIOLATION":
       return "Resolve the new policy violation or record baseline if adopted debt before completion.";
     case "E_POLICY_WEAKENING":
@@ -433,6 +454,27 @@ export async function evaluateCompletion({
     coverage = receipt?.value?.evidenceCoverage ?? [];
   }
 
+  if (contract && route && state) {
+    const qualityChecks = [...new Map([
+      ...(state.checks ?? []),
+      ...(receipt?.value?.checks ?? []),
+    ].filter((check) => check?.kind === "structural-quality").map((check) => [check.id, check])).values()];
+    for (const check of qualityChecks) {
+      const provenanceErrors = await validateStructuralQualityCheckProvenance(check, {
+        target,
+        packageRoot,
+        taskId: contract.value.taskId,
+        state,
+        contract,
+        route,
+        runtimeContext,
+      });
+      for (const error of provenanceErrors) {
+        errors.push(issue(error.code ?? "E_STRUCTURAL_QUALITY_EVIDENCE_STALE", error.message, error.artifacts ?? [stateRel, receiptRel]));
+      }
+    }
+  }
+
   const ledger = contract && state
     ? await validateLedger(target, taskId, contract.value.taskId, state, errors, packageRoot, { eventsPath, statePath })
     : { valid: false, events: [], errors: [] };