@cassiomc1/forgeloop 1.8.0 → 1.9.0

package/schemas/structural-quality.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/structural-quality.schema.json",
+  "title": "ForgeLoop structural quality evidence",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "role", "taskId", "capturedAt", "verificationCycle", "attempt", "bindings", "provider", "scope", "status", "reasonCodes"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "role": { "enum": ["BASELINE", "EVALUATION"] },
+    "taskId": { "type": "string", "minLength": 1 },
+    "capturedAt": { "type": "string", "minLength": 1 },
+    "verificationCycle": { "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }] },
+    "attempt": { "type": "integer", "minimum": 1 },
+    "status": { "enum": ["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"] },
+    "reasonCodes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "errorCode": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "baselineSignal": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+    "currentSignal": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+    "bindings": {
+      "type": "object",
+      "required": ["contractFingerprint", "routeFingerprint", "policyFingerprint", "scopeFingerprint"],
+      "properties": {
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "policyFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "scopeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "baselineFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "sourceMaterialFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "stateRevision": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "sourceObservation": {
+      "type": "object",
+      "required": ["beforeFingerprint", "afterFingerprint", "stable"],
+      "properties": {
+        "beforeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "afterFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "stable": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "provider": {
+      "type": "object",
+      "required": ["id", "version", "transport", "executionMode"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "transport": { "type": "string", "minLength": 1 },
+        "executionMode": { "type": "string", "minLength": 1 },
+        "measurementModel": { "type": "string", "minLength": 1 },
+        "compatibilityKey": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "detection": {
+      "type": "object",
+      "required": ["available", "providerId", "transport", "reasonCode"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "providerId": { "type": "string", "minLength": 1 },
+        "providerVersion": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "transport": { "type": "string", "minLength": 1 },
+        "measurementModel": { "type": "string", "minLength": 1 },
+        "compatibilityKey": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "reasonCode": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "projectRoot"],
+      "properties": {
+        "kind": { "const": "PROJECT" },
+        "projectRoot": { "const": "." },
+        "providerConfigFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "architectureRulesFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "snapshot": { "$ref": "#/$defs/snapshot" },
+    "comparison": { "$ref": "#/$defs/comparison" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "rootCause": {
+      "type": "object",
+      "required": ["score", "raw"],
+      "properties": {
+        "score": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "raw": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "snapshot": {
+      "type": "object",
+      "required": ["qualitySignal", "bottleneck", "rootCauses", "statistics", "diagnostics"],
+      "properties": {
+        "qualitySignal": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "bottleneck": { "enum": ["modularity", "acyclicity", "depth", "equality", "redundancy"] },
+        "rootCauses": {
+          "type": "object",
+          "required": ["modularity", "acyclicity", "depth", "equality", "redundancy"],
+          "properties": {
+            "modularity": { "$ref": "#/$defs/rootCause" },
+            "acyclicity": { "$ref": "#/$defs/rootCause" },
+            "depth": { "$ref": "#/$defs/rootCause" },
+            "equality": { "$ref": "#/$defs/rootCause" },
+            "redundancy": { "$ref": "#/$defs/rootCause" }
+          },
+          "additionalProperties": false
+        },
+        "statistics": {
+          "type": "object",
+          "required": ["files", "lines", "importEdges", "crossModuleEdges"],
+          "properties": {
+            "files": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "lines": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "importEdges": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "crossModuleEdges": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }
+          },
+          "additionalProperties": false
+        },
+        "diagnostics": { "oneOf": [{ "type": "object" }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "comparison": {
+      "type": "object",
+      "required": ["comparable", "qualityDelta", "rootCauseDeltas", "status", "reasonCodes"],
+      "properties": {
+        "comparable": { "type": "boolean" },
+        "qualityDelta": { "oneOf": [{ "type": "integer" }, { "type": "null" }] },
+        "rootCauseDeltas": { "type": "object" },
+        "failedConditions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "status": { "enum": ["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "role": { "const": "BASELINE" } } },
+      "then": {
+        "required": ["sourceObservation"],
+        "properties": {
+          "bindings": {
+            "required": ["sourceMaterialFingerprint"],
+            "properties": {
+              "sourceMaterialFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          },
+          "sourceObservation": { "properties": { "stable": { "const": true } } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["PASS", "FAIL"] } } },
+      "then": {
+        "required": ["sourceObservation"],
+        "properties": {
+          "bindings": {
+            "required": ["sourceMaterialFingerprint"],
+            "properties": {
+              "sourceMaterialFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          },
+          "sourceObservation": { "properties": { "stable": { "const": true } } }
+        }
+      }
+    }
+  ]
+}

package/src/cli.js

@@ -13,6 +13,9 @@ import { formatValidateProtocolResult } from "./commands/validate-protocol.js";
 import { formatActivateResult } from "./commands/activate.js";
 import { formatAdvanceResult } from "./commands/advance.js";
 import { formatPreflightResult } from "./commands/preflight.js";
+import { formatQualityBaselineResult } from "./commands/quality-baseline.js";
+import { formatQualityVerifyResult } from "./commands/quality-verify.js";
+import { formatQualityStatusResult } from "./commands/quality-status.js";
 import { formatCompleteResult } from "./commands/complete.js";
 import { formatAuditResult } from "./commands/audit.js";
 import { formatReportResult } from "./commands/report.js";
@@ -379,6 +382,21 @@ export const COMMAND_HANDLERS = Object.freeze({
     renderJsonOr(options, result, formatPreflightResult);
     return exitCode;
   },
+  "quality-baseline": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["quality-baseline"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatQualityBaselineResult);
+    return exitCode;
+  },
+  "quality-verify": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["quality-verify"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatQualityVerifyResult);
+    return exitCode;
+  },
+  "quality-status": async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS["quality-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatQualityStatusResult);
+    return exitCode;
+  },
   advance: async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS.advance({ target, packageRoot, options });
     renderJsonOr(options, result, formatAdvanceResult);

package/src/commands/quality-baseline.js

@@ -0,0 +1,28 @@
+import { withTaskMutation } from "../core/task-command.js";
+import { captureStructuralQualityBaseline } from "../core/structural-quality/service.js";
+
+export async function runQualityBaseline({ target, packageRoot, taskId, replace = false, timeoutMs, runtimeContext } = {}) {
+  return withTaskMutation(target, { taskId, packageRoot }, "quality-baseline", async (ctx) => captureStructuralQualityBaseline({
+    target,
+    packageRoot,
+    taskId: ctx?.taskId ?? taskId,
+    replace,
+    timeoutMs,
+    runtimeContext,
+  }));
+}
+
+export function formatQualityBaselineResult(result) {
+  return [
+    "FORGELOOP STRUCTURAL QUALITY BASELINE",
+    `status: ${result.status}`,
+    `mode: ${result.mode}`,
+    `provider: ${result.provider?.id ?? "not-requested"}`,
+    `provider-version: ${result.provider?.version ?? "unknown"}`,
+    `quality: ${result.baseline?.snapshot?.qualitySignal ?? "none"}`,
+    `bottleneck: ${result.baseline?.snapshot?.bottleneck ?? "none"}`,
+    `artifact: ${result.artifactRef ?? "none"}`,
+    `next: ${result.mode === "gate" ? "VERIFY_STRUCTURAL_QUALITY" : "none"}`,
+    "",
+  ].join("\n");
+}

package/src/commands/quality-status.js

@@ -0,0 +1,34 @@
+import { withResolvedTask } from "../core/task-command.js";
+import { projectStructuralQualityStatus } from "../core/structural-quality/status.js";
+
+export async function runQualityStatus({ target, packageRoot, taskId, runtimeContext } = {}) {
+  return withResolvedTask(target, { taskId, packageRoot }, async (ctx) => projectStructuralQualityStatus({
+    target,
+    packageRoot,
+    taskId: ctx?.taskId ?? taskId,
+    runtimeContext,
+  }), { explicitRequired: true });
+}
+
+export function formatQualityStatusResult(result) {
+  const status = result.mode === "off"
+    ? "OFF"
+    : result.current.status === "PASS"
+      ? "PASS"
+      : result.current.status === "FAIL"
+        ? "FAIL"
+        : result.current.status === "BLOCKED" || (result.mode === "gate" && result.baseline.status !== "OBSERVED")
+          ? "BLOCKED"
+          : "NOT OBSERVED";
+  return [
+    `STRUCTURAL QUALITY: ${status}`,
+    `mode: ${result.mode}`,
+    `provider: ${result.provider ?? "none"}`,
+    `baseline: ${result.baseline.status}`,
+    `current: ${result.current.status}`,
+    `quality: ${result.current.qualitySignal ?? result.baseline.qualitySignal ?? "none"}`,
+    `delta: ${result.current.delta ?? "none"}`,
+    `next: ${result.next ?? "none"}`,
+    "",
+  ].join("\n");
+}

package/src/commands/quality-verify.js

@@ -0,0 +1,30 @@
+import { evaluateStructuralQuality } from "../core/structural-quality/service.js";
+
+export async function runQualityVerify({ target, packageRoot, taskId, timeoutMs, authorityContext, runtimeContext } = {}) {
+  return evaluateStructuralQuality({
+    target,
+    packageRoot,
+    taskId,
+    timeoutMs,
+    authorityContext,
+    runtimeContext,
+  });
+}
+
+export function formatQualityVerifyResult(result) {
+  return [
+    "FORGELOOP STRUCTURAL QUALITY VERIFICATION",
+    `status: ${result.evaluation?.status ?? result.status}`,
+    `cycle: ${result.evaluation?.verificationCycle ?? "none"}`,
+    `attempt: ${result.evaluation?.attempt ?? "none"}`,
+    `provider: ${result.evaluation?.provider?.id ?? "none"}`,
+    `provider-version: ${result.evaluation?.provider?.version ?? "unknown"}`,
+    `quality: ${result.evaluation?.currentSignal ?? result.evaluation?.snapshot?.qualitySignal ?? "none"}`,
+    `delta: ${result.evaluation?.comparison?.qualityDelta ?? "none"}`,
+    `bottleneck: ${result.evaluation?.snapshot?.bottleneck ?? "none"}`,
+    `artifact: ${result.evaluation?.artifactRef ?? "none"}`,
+    `check: ${result.check?.status ?? "not-recorded"}`,
+    `next: ${result.evaluation?.status === "FAIL" ? "DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION" : result.evaluation?.status === "BLOCKED" ? "RESOLVE_STRUCTURAL_QUALITY_BLOCKER" : "none"}`,
+    "",
+  ].join("\n");
+}

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",

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";
@@ -132,6 +135,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,