@cassiomc1/forgeloop 1.8.0 → 1.9.0

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,
@@ -130,6 +131,17 @@ 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}`);
   }

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: [] };

package/src/core/config.js

@@ -3,6 +3,7 @@ import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts
 import { E_ATTESTATION_CONFIGURATION_INVALID } from "./error-codes.js";
 import { normalizeVerificationConfiguration } from "./verification-scope-capability.js";
 import { EXECUTION_PROFILE_REQUESTS } from "./execution-profile.js";
+import { normalizeStructuralQualityConfig } from "./structural-quality/policy.js";
 
 export const CONFIG_SCHEMA_VERSION = 1;
 export const COMPLIANCE_MODES = Object.freeze(["advisory", "standard", "strict"]);
@@ -80,6 +81,7 @@ export function createConfig(input = {}) {
     }
     executionProfile = input.executionProfile;
   }
+  const structuralQuality = normalizeStructuralQualityConfig(input.structuralQuality);
   return {
     schemaVersion: CONFIG_SCHEMA_VERSION,
     protocolVersion: PROTOCOL_VERSION,
@@ -90,6 +92,7 @@ export function createConfig(input = {}) {
     ...(verification ? { verification } : {}),
     ...(attestation ? { attestation } : {}),
     ...(executionProfile ? { executionProfile } : {}),
+    ...(structuralQuality !== undefined ? { structuralQuality } : {}),
   };
 }
 

package/src/core/error-codes.js

@@ -83,6 +83,57 @@ export const E_EXECUTION_PROFILE_SAFETY_FLOOR_INVALID = "E_EXECUTION_PROFILE_SAF
 export const E_USAGE_INVALID = "E_USAGE_INVALID";
 export const E_USAGE_SOURCE_INVALID = "E_USAGE_SOURCE_INVALID";
 export const E_EFFICIENCY_BASELINE_INVALID = "E_EFFICIENCY_BASELINE_INVALID";
+export const E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID = "E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID";
+export const E_STRUCTURAL_QUALITY_PROVIDER_INVALID = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+export const E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE = "E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE";
+export const E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED = "E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED";
+export const E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID = "E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID";
+export const E_STRUCTURAL_QUALITY_PROVIDER_TOOL_CONTRACT_INVALID = "E_STRUCTURAL_QUALITY_PROVIDER_TOOL_CONTRACT_INVALID";
+export const E_STRUCTURAL_QUALITY_SCAN_FAILED = "E_STRUCTURAL_QUALITY_SCAN_FAILED";
+export const E_STRUCTURAL_QUALITY_TIMEOUT = "E_STRUCTURAL_QUALITY_TIMEOUT";
+export const E_STRUCTURAL_QUALITY_OUTPUT_LIMIT = "E_STRUCTURAL_QUALITY_OUTPUT_LIMIT";
+export const E_STRUCTURAL_QUALITY_BASELINE_MISSING = "E_STRUCTURAL_QUALITY_BASELINE_MISSING";
+export const E_STRUCTURAL_QUALITY_BASELINE_EXISTS = "E_STRUCTURAL_QUALITY_BASELINE_EXISTS";
+export const E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID = "E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID";
+export const E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH = "E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH";
+export const E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE = "E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE";
+export const E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH = "E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH";
+export const E_STRUCTURAL_QUALITY_EVIDENCE_STALE = "E_STRUCTURAL_QUALITY_EVIDENCE_STALE";
+export const E_STRUCTURAL_QUALITY_SOURCE_DRIFT = "E_STRUCTURAL_QUALITY_SOURCE_DRIFT";
+export const E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE = "E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE";
+export const E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE = "E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE";
+export const E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE = "E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE";
+export const E_STRUCTURAL_QUALITY_REGRESSION = "E_STRUCTURAL_QUALITY_REGRESSION";
+
+const STRUCTURAL_QUALITY_ERROR_METADATA = Object.freeze(Object.fromEntries([
+  [E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID, "Correct structuralQuality mode, provider ID, budgets, floors, or optimization limits in .forgeloop/config.json."],
+  [E_STRUCTURAL_QUALITY_PROVIDER_INVALID, "Use a provider implementing id, detect(input), and scan(input) with the documented normalized boundary."],
+  [E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE, "Install or expose the requested provider outside ForgeLoop, or use observe mode and record the limitation; ForgeLoop never auto-installs it."],
+  [E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED, "Use a verified Sentrux version (0.5.5, 0.5.6, or 0.5.7), or select a compatible provider through trusted runtime context."],
+  [E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID, "Repair the provider MCP handshake or response shape; malformed external data cannot become evidence."],
+  [E_STRUCTURAL_QUALITY_PROVIDER_TOOL_CONTRACT_INVALID, "Ensure the provider exposes the required scan and health tool argument schemas."],
+  [E_STRUCTURAL_QUALITY_SCAN_FAILED, "Inspect the provider failure and rerun quality-baseline or quality-verify after the external analyzer is healthy."],
+  [E_STRUCTURAL_QUALITY_TIMEOUT, "Use a responsive provider or a bounded timeout within the supported limit; never promote a timed-out scan."],
+  [E_STRUCTURAL_QUALITY_OUTPUT_LIMIT, "Reduce provider output or diagnostics; the 2 MiB combined process-output limit is fail-closed."],
+  [E_STRUCTURAL_QUALITY_BASELINE_MISSING, "Run forgeloop quality-baseline --task <id> after PLANNED and before EXECUTING."],
+  [E_STRUCTURAL_QUALITY_BASELINE_EXISTS, "Use the existing immutable baseline or request --replace while the task is still before EXECUTING."],
+  [E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID, "Baseline replacement is forbidden after EXECUTING; repair the current task against its original baseline."],
+  [E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH, "Reconcile contract, route, policy, scope, provider, or rules drift before using the baseline."],
+  [E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE, "Restore the baseline provider/version/rules/policy/scope bindings and rerun quality-verify."],
+  [E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH, "Use a compatible measurement model and provider across baseline and evaluation observations."],
+  [E_STRUCTURAL_QUALITY_EVIDENCE_STALE, "Rerun quality-verify in the active verification cycle and refresh completion through the canonical receipt pipeline."],
+  [E_STRUCTURAL_QUALITY_SOURCE_DRIFT, "Ensure the worktree is not mutated during provider observation and rerun quality-baseline or quality-verify."],
+  [E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE, "Repair unreadable or unsafe source material before structural-quality evidence can be trusted."],
+  [E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE, "Rerun quality-verify under the active task epoch without concurrent state mutations."],
+  [E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE, "Rerun quality-verify to reconcile and project the canonical check from the existing evaluation artifact."],
+  [E_STRUCTURAL_QUALITY_REGRESSION, "Use the bottleneck and root-cause deltas to record an evidence-backed diagnosis, correct within scope, and verify a new cycle."],
+].map(([code, safeResolution]) => [code, Object.freeze({
+  code,
+  category: "structural-quality",
+  classification: "PUBLIC_STABLE",
+  meaning: "Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary.",
+  safeResolution,
+})])));
 
 const EXTENSION_PUBLIC_ERROR_CODES = Object.freeze(Object.fromEntries([
   E_WORKSPACE_IDENTITY_UNAVAILABLE,
@@ -227,6 +278,7 @@ export const E_TRAJECTORY_REFERENCE_REQUIRED = "E_TRAJECTORY_REFERENCE_REQUIRED"
  */
 export const PUBLIC_ERROR_CODES = Object.freeze({
   ...EXTENSION_PUBLIC_ERROR_CODES,
+  ...STRUCTURAL_QUALITY_ERROR_METADATA,
   E_PREFLIGHT_NOT_READY: Object.freeze({
     code: "E_PREFLIGHT_NOT_READY",
     category: "preflight",
@@ -1044,6 +1096,27 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_USAGE_INVALID,
   E_USAGE_SOURCE_INVALID,
   E_EFFICIENCY_BASELINE_INVALID,
+  E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID,
+  E_STRUCTURAL_QUALITY_PROVIDER_INVALID,
+  E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE,
+  E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED,
+  E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID,
+  E_STRUCTURAL_QUALITY_PROVIDER_TOOL_CONTRACT_INVALID,
+  E_STRUCTURAL_QUALITY_SCAN_FAILED,
+  E_STRUCTURAL_QUALITY_TIMEOUT,
+  E_STRUCTURAL_QUALITY_OUTPUT_LIMIT,
+  E_STRUCTURAL_QUALITY_BASELINE_MISSING,
+  E_STRUCTURAL_QUALITY_BASELINE_EXISTS,
+  E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID,
+  E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH,
+  E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE,
+  E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH,
+  E_STRUCTURAL_QUALITY_EVIDENCE_STALE,
+  E_STRUCTURAL_QUALITY_SOURCE_DRIFT,
+  E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE,
+  E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE,
+  E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE,
+  E_STRUCTURAL_QUALITY_REGRESSION,
   E_RECONCILE_NOT_STALE,
   E_RECONCILE_PHASE_INVALID,
   E_RECONCILE_UNSUPPORTED_DRIFT,

package/src/core/filesystem.js

@@ -73,6 +73,22 @@ export function ensureWithin(root, relativePath) {
   return path.join(root, normalized);
 }
 
+export function isPathWithin(root, candidate, { platform = process.platform } = {}) {
+  const pathApi = platform === "win32" ? path.win32 : path;
+  const normalizeForComparison = (value) => {
+    const normalized = pathApi.normalize(value);
+    return platform === "win32" ? normalized.toLowerCase() : normalized;
+  };
+  const relative = pathApi.relative(
+    normalizeForComparison(root),
+    normalizeForComparison(candidate),
+  );
+  return relative === ""
+    || (relative !== ".."
+      && !relative.startsWith(`..${pathApi.sep}`)
+      && !pathApi.isAbsolute(relative));
+}
+
 export async function assertSafePath(root, relativePath) {
   const destination = ensureWithin(root, relativePath);
   const absoluteRoot = path.resolve(root);
@@ -105,8 +121,7 @@ export async function assertSafePath(root, relativePath) {
       }
       const resolvedRoot = await realpathWithTransientWindowsRetry(absoluteRoot);
       const resolvedExisting = await realpathWithTransientWindowsRetry(existing);
-      const relativeResolved = path.relative(resolvedRoot, resolvedExisting);
-      if (relativeResolved === ".." || relativeResolved.startsWith(`..${path.sep}`) || path.isAbsolute(relativeResolved)) {
+      if (!isPathWithin(resolvedRoot, resolvedExisting)) {
         throw new Error(`Path escapes target directory: ${relativePath}`);
       }
       return destination;
@@ -186,4 +201,4 @@ export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {})
     }
     throw error;
   }
-}
+}

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([
@@ -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,
@@ -203,6 +206,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 +246,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

@@ -18,6 +18,7 @@ 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 +78,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 +159,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,6 +184,13 @@ 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 }) };
   }

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,
   });
 }
 

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

@@ -1,5 +1,5 @@
 import { ARTIFACT_PATHS, readJsonArtifact } from "./artifacts.js";
-import { taskArtifactPath } from "./task-paths.js";
+import { taskArtifactPath, taskStructuralQualityDirectory } from "./task-paths.js";
 import { completionIdentityErrors, evaluateCompletion } from "./completion.js";
 import { readContract } from "./contract.js";
 import { evaluatePreflight, validatePersistedPreflight } from "./preflight.js";
@@ -20,6 +20,7 @@ import { listActions } from "./actions.js";
 import { listApprovals } from "./approvals.js";
 import { loadPolicyIdentity } from "./policy-engine.js";
 import { evaluateContinuityNextAction } from "./next-action-continuity.js";
+import { projectStructuralQualityStatus } from "./structural-quality/service.js";
 
 export const PHASES_REQUIRING_EXECUTION_CHRONOLOGY = new Set([
   "EXECUTING",
@@ -34,6 +35,24 @@ export function phaseRequiresExecutionChronology(phase) {
   return PHASES_REQUIRING_EXECUTION_CHRONOLOGY.has(phase);
 }
 
+function structuralQualityOptionalActions(quality, taskId) {
+  if (quality?.mode !== "observe") return [];
+  if (quality.baseline?.status !== "OBSERVED") {
+    return [{
+      action: NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE,
+      command: `forgeloop quality-baseline --task ${taskId} --json`,
+    }];
+  }
+  if (quality.freshness === "STALE" || quality.current?.verificationCycle === null
+    || quality.current?.verificationCycle === undefined) {
+    return [{
+      action: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+      command: `forgeloop quality-verify --task ${taskId} --json`,
+    }];
+  }
+  return [];
+}
+
 export async function resolveNextActionPhase({
   target,
   packageRoot,
@@ -434,7 +453,7 @@ export async function resolveNextActionPhase({
   let executionPrerequisites = null;
   if (phaseNeedsChronology) {
     try {
-      executionPrerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId });
+      executionPrerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId, runtimeContext });
     } catch (error) {
       return result({
         ...context,
@@ -506,7 +525,17 @@ export async function resolveNextActionPhase({
     return decision(context, NEXT_ACTIONS.PLAN, artifactError("PHASE_DESIGNING", "Required gates are ready for planning"));
   }
   if (state.phase === "PLANNED") {
-    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId });
+    const quality = await projectStructuralQualityStatus({ target, packageRoot, taskId: explicitTaskId ?? state.taskId, runtimeContext });
+    if (quality.mode === "gate" && quality.baseline.status !== "OBSERVED") {
+      return result({
+        ...context,
+        nextAction: NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE,
+        commands: [commandFor(NEXT_ACTIONS.CAPTURE_STRUCTURAL_QUALITY_BASELINE).replace("<id>", state.taskId)],
+        reasons: [artifactError("E_STRUCTURAL_QUALITY_BASELINE_MISSING", "Gate mode requires a structural-quality baseline before execution", [quality.baseline.artifactRef ?? taskArtifactPath(state.taskId, "structuralQuality")])],
+        requiredArtifacts: [taskArtifactPath(state.taskId, "structuralQuality")],
+      });
+    }
+    const prerequisites = await evaluateStartExecutionPrerequisites({ target, state, packageRoot, taskId: explicitTaskId, runtimeContext });
     if (prerequisites.errors.length > 0) {
       const preflightOnly = prerequisites.errors.every((error) => error.code.startsWith("E_PREFLIGHT_")
         || (error.code === "E_PHASE_CHRONOLOGY_INVALID"
@@ -530,7 +559,14 @@ export async function resolveNextActionPhase({
         missingArtifacts: preflightArtifact.missingArtifacts,
       });
     }
-    return decision(context, NEXT_ACTIONS.START_EXECUTION, artifactError("PHASE_PLANNED", "The persisted preflight is READY"));
+    return decision(
+      context,
+      NEXT_ACTIONS.START_EXECUTION,
+      artifactError("PHASE_PLANNED", "The persisted preflight is READY"),
+      [],
+      [],
+      structuralQualityOptionalActions(quality, state.taskId),
+    );
   }
   if (state.phase === "EXECUTING") {
     const continuityAction = await evaluateContinuityNextAction({ target, packageRoot, context });
@@ -538,6 +574,41 @@ export async function resolveNextActionPhase({
     return decision(context, NEXT_ACTIONS.ENTER_VERIFYING, artifactError("PHASE_EXECUTING", "Execution is complete enough to enter verification"));
   }
   if (state.phase === "VERIFYING") {
+    const quality = await projectStructuralQualityStatus({ target, packageRoot, taskId: explicitTaskId ?? state.taskId, runtimeContext });
+    if (quality.mode === "gate") {
+      if (quality.baseline.status !== "OBSERVED") {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.RESOLVE_STRUCTURAL_QUALITY_BLOCKER,
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_BASELINE_MISSING", "Structural-quality gate cannot verify without its immutable baseline", [taskArtifactPath(state.taskId, "structuralQuality")])],
+          requiredArtifacts: [taskArtifactPath(state.taskId, "structuralQuality")],
+        });
+      }
+      if (!quality.current.artifactRef || quality.current.verificationCycle !== (state.verificationCycle ?? 1)) {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+          commands: [commandFor(NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY).replace("<id>", state.taskId)],
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "The current verification cycle has no structural-quality evaluation", [taskStructuralQualityDirectory(state.taskId)])],
+          requiredArtifacts: [taskStructuralQualityDirectory(state.taskId)],
+        });
+      }
+      if (quality.freshness === "STALE") {
+        return result({
+          ...context,
+          nextAction: NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY,
+          commands: [commandFor(NEXT_ACTIONS.VERIFY_STRUCTURAL_QUALITY).replace("<id>", state.taskId)],
+          reasons: [artifactError("E_STRUCTURAL_QUALITY_EVIDENCE_STALE", "Structural-quality evidence is stale; fresh verification is required before review", [quality.current.artifactRef])],
+          requiredArtifacts: [taskStructuralQualityDirectory(state.taskId)],
+        });
+      }
+      if (quality.current.status === "FAIL") {
+        return decision(context, NEXT_ACTIONS.DIAGNOSE_STRUCTURAL_QUALITY_REGRESSION, artifactError("E_STRUCTURAL_QUALITY_REGRESSION", "Structural-quality verification detected a regression", [quality.current.artifactRef]));
+      }
+      if (quality.current.status === "BLOCKED") {
+        return decision(context, NEXT_ACTIONS.RESOLVE_STRUCTURAL_QUALITY_BLOCKER, artifactError("E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE", "Structural-quality verification is blocked", [quality.current.artifactRef]));
+      }
+    }
     const invalidChecks = checkListReasons(state);
     if (invalidChecks.length > 0) {
       return result({
@@ -655,7 +726,14 @@ export async function resolveNextActionPhase({
       });
     }
     if (readiness.ready) {
-      return decision(context, NEXT_ACTIONS.ENTER_REVIEWING, artifactError("EVIDENCE_COVERED", "All required observed verification evidence is covered"));
+      return decision(
+        context,
+        NEXT_ACTIONS.ENTER_REVIEWING,
+        artifactError("EVIDENCE_COVERED", "All required observed verification evidence is covered"),
+        [],
+        [],
+        structuralQualityOptionalActions(quality, state.taskId),
+      );
     }
     const uncovered = [...readiness.invalid, ...readiness.partial, ...readiness.missing];
     return result({
@@ -674,6 +752,7 @@ export async function resolveNextActionPhase({
           [stateRel],
         )),
       requiredArtifacts: requiredArtifacts,
+      optionalActions: structuralQualityOptionalActions(quality, state.taskId),
     });
   }
   if (state.phase === "DIAGNOSING") {