@cassiomc1/forgeloop 1.8.1 → 1.10.0

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") {

package/src/core/phase.js

@@ -26,6 +26,7 @@ import {
   buildInformationGainProjection,
   evaluateStructuredDiagnosticStall,
 } from "./information-gain-projection.js";
+import { assertStructuralQualityExecutionReady } from "./structural-quality/service.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -134,9 +135,16 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
       throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${routeRel}: ${error.message}`, [routeRel]);
     }
   }
+  if (toPhase === "EXECUTING" && scopedTaskId) {
+    try {
+      await assertStructuralQualityExecutionReady({ target, packageRoot, taskId: scopedTaskId, runtimeContext });
+    } catch (error) {
+      throw phaseError(error.code, error.message, error.artifacts);
+    }
+  }
   if (hasExecutionStarted(toPhase)) {
     try {
-      await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId });
+      await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId, runtimeContext });
     } catch (error) {
       throw phaseError(error.code, error.message, error.artifacts);
     }

package/src/core/portable-context.js

@@ -0,0 +1,103 @@
+import { assertJsonLimits } from "./json-safety.js";
+import { assertSecretFree } from "./receipt.js";
+import { E_PORTABLE_CONTEXT_INVALID } from "./error-codes.js";
+
+export class PortableContextError extends Error {
+  constructor(message, { code = E_PORTABLE_CONTEXT_INVALID, cause } = {}) {
+    super(message, cause !== undefined ? { cause } : undefined);
+    this.name = "PortableContextError";
+    this.code = code;
+  }
+}
+
+const PORTABLE_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /(?:^|\s)(?:sk|ghp|glpat|xox[baprs])-[-_a-z0-9]{8,}/i,
+  /(?:AKIA|ASIA)[A-Z0-9]{12,}/,
+  /(?:bearer\s+[-_a-z0-9\.]{4,})/i,
+  /(?:authorization:\s*bearer)/i,
+];
+
+function containsSecretPattern(str) {
+  return PORTABLE_SECRET_PATTERNS.some((pattern) => pattern.test(str));
+}
+
+function checkObjectForSecrets(value, location = "$") {
+  if (typeof value === "string") {
+    if (containsSecretPattern(value)) {
+      throw new Error(`${location}: secret-like value is not allowed`);
+    }
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => checkObjectForSecrets(item, `${location}[${index}]`));
+  } else {
+    for (const [key, child] of Object.entries(value)) {
+      checkObjectForSecrets(child, `${location}.${key}`);
+    }
+  }
+}
+
+export function normalizePortableText(
+  value,
+  {
+    label = "portable text",
+    maxLength,
+    optional = false,
+  } = {},
+) {
+  if (value === undefined || value === null) {
+    if (optional) return null;
+    throw new PortableContextError(`${label} is required`);
+  }
+
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new PortableContextError(`${label} must be a non-empty string`);
+  }
+
+  if (typeof maxLength === "number" && value.length > maxLength) {
+    throw new PortableContextError(`${label} exceeds the ${maxLength}-character limit`);
+  }
+
+  if (/\p{Cc}/u.test(value)) {
+    throw new PortableContextError(`${label} contains control characters`);
+  }
+
+  return value;
+}
+
+export function assertPortableContextSafe(
+  value,
+  {
+    label = "portable context",
+  } = {},
+) {
+  try {
+    assertJsonLimits(value, label);
+    assertSecretFree(value);
+    checkObjectForSecrets(value, label);
+    return value;
+  } catch (error) {
+    if (error.code === E_PORTABLE_CONTEXT_INVALID) {
+      throw error;
+    }
+    throw new PortableContextError(
+      `${label} failed safety verification: ${error.message}`,
+      { code: E_PORTABLE_CONTEXT_INVALID, cause: error },
+    );
+  }
+}
+
+export function deepFreeze(object) {
+  if (object === null || typeof object !== "object" || Object.isFrozen(object)) {
+    return object;
+  }
+  Object.freeze(object);
+  for (const value of Object.values(object)) {
+    if (value !== null && typeof value === "object") {
+      deepFreeze(value);
+    }
+  }
+  return object;
+}

package/src/core/preflight.js

@@ -28,6 +28,7 @@ import { PROFILE_PATH } from "./target-layout.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { validateEventLedger } from "./events.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
+import { normalizeStructuralQualityConfig } from "./structural-quality/policy.js";
 
 const PREVIEW_DECISION_LIMIT = 10;
 const PREVIEW_DECISION_MAX_LENGTH = 240;
@@ -42,6 +43,17 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
   const contract = await loadContract(target, packageRoot, errors, { taskId, contractPath });
   const route = await loadRoute(target, packageRoot, errors, { taskId, routePath });
   const config = await optionalConfig(target, packageRoot, errors);
+  if (config.structuralQuality !== undefined) {
+    try {
+      normalizeStructuralQualityConfig(config.structuralQuality);
+    } catch (error) {
+      errors.push(issue(
+        error.code ?? "E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID",
+        error.message,
+        [PROJECT_ARTIFACT_PATHS.config],
+      ));
+    }
+  }
   const effectiveStrict = strict || config.complianceMode === "strict";
   if (effectiveStrict && profile.status !== "verified") {
     errors.push(issue("E_PROFILE_UNVERIFIED", "Strict preflight requires a verified project profile", [PROFILE_PATH]));
@@ -111,6 +123,26 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
 
   const sortedErrors = sortIssues(errors);
   const effectiveTaskId = taskId ?? contract?.value?.taskId ?? state?.taskId ?? "unknown";
+  let structuralQuality = {
+    mode: config.structuralQuality?.mode ?? "off",
+    provider: config.structuralQuality?.mode && config.structuralQuality.mode !== "off"
+      ? config.structuralQuality.provider ?? "sentrux"
+      : null,
+    baseline: { status: config.structuralQuality?.mode && config.structuralQuality.mode !== "off" ? "MISSING" : "NOT_REQUESTED" },
+    current: { status: "NOT_OBSERVED" },
+    comparable: null,
+    completionRequired: config.structuralQuality?.mode === "gate",
+    reasonCodes: [],
+    next: config.structuralQuality?.mode === "gate" ? "CAPTURE_STRUCTURAL_QUALITY_BASELINE" : null,
+  };
+  if (effectiveTaskId !== "unknown") {
+    try {
+      const { projectStructuralQualityStatus } = await import("./structural-quality/service.js");
+      structuralQuality = await projectStructuralQualityStatus({ target, packageRoot, taskId: effectiveTaskId });
+    } catch (error) {
+      structuralQuality.reasonCodes = [error.code ?? "E_STRUCTURAL_QUALITY_EVIDENCE_STALE"];
+    }
+  }
   return {
     schemaVersion: 1,
     protocolVersion: 1,
@@ -140,6 +172,7 @@ export async function evaluatePreflight({ target, packageRoot, strict = false, t
       },
     } : {}),
     ...(sources ? { sources: { status: "valid", fingerprint: null } } : {}),
+    structuralQuality,
   };
 }
 

package/src/core/protocol-info.js

@@ -83,6 +83,21 @@ export function protocolInfo({ packageVersion = null } = {}) {
         informationGainV2: true,
         strategyOscillationDetection: true,
       },
+      structuralQuality: {
+        version: 1,
+        supported: true,
+        schemaVersion: 1,
+        modes: ["off", "observe", "gate"],
+        builtInProviders: ["sentrux"],
+        commands: ["quality-baseline", "quality-verify", "quality-status"],
+        resource: "task/structural-quality",
+        providerNeutral: true,
+        defaultProvider: "sentrux",
+        transport: "mcp-stdio",
+        rootCauses: ["modularity", "acyclicity", "depth", "equality", "redundancy"],
+        baselineImmutableAfterExecution: true,
+        optimizationMaxExtraEvaluations: 2,
+      },
       durableActions: {
         version: 1,
         supported: true,
@@ -145,11 +160,27 @@ export function protocolInfo({ packageVersion = null } = {}) {
         rebinding: "EXPLICIT_ONLY",
       },
       canonicalHandoffs: {
-        version: 1,
+        version: 2,
         supported: true,
         immutable: true,
-        actorControlledIntent: true,
         lifecycleAuthority: false,
+        evidenceAuthority: false,
+        exactlyOnceAcceptance: true,
+        acceptanceLedgerBacked: true,
+        acceptanceCommand: "handoff-accept",
+        acceptanceStatuses: ["OPEN", "ACCEPTED", "UNBOUND", "INCONSISTENT"],
+      },
+      advisoryContextProviders: {
+        version: 1,
+        supported: true,
+        providerNeutral: true,
+        integrationApiOnly: true,
+        lazy: true,
+        optIn: true,
+        persistedByForgeLoop: false,
+        lifecycleAuthority: false,
+        evidenceAuthority: false,
+        executable: false,
       },
       responsibilityConstraints: {
         version: 1,

package/src/core/runtime-context.js

@@ -3,6 +3,9 @@ import {
   isVerificationExecutionAdapter,
   normalizeVerificationExecutionPolicy,
 } from "./verification-execution.js";
+import { STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN } from "./structural-quality/constants.js";
+import { E_ADVISORY_CONTEXT_PROVIDER_INVALID } from "./error-codes.js";
+import { assertAdvisoryContextProviderIdentity } from "./advisory-context/provider.js";
 
 export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
 
@@ -105,5 +108,60 @@ export function createForgeLoopContext(options = {}) {
     }
     context.usageProvider = options.usageProvider;
   }
+  if (options?.structuralQualityProviders !== undefined) {
+    const configured = options.structuralQualityProviders instanceof Map
+      ? Object.fromEntries(options.structuralQualityProviders.entries())
+      : options.structuralQualityProviders;
+    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+      const error = new Error("structuralQualityProviders must be an object or Map");
+      error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+      throw error;
+    }
+    const providers = {};
+    for (const [id, provider] of Object.entries(configured)) {
+      if (!STRUCTURAL_QUALITY_PROVIDER_ID_PATTERN.test(id) || id === "sentrux") {
+        const error = new Error(`Invalid or reserved structural-quality provider ID: ${id}`);
+        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+        throw error;
+      }
+      if (typeof provider !== "function"
+        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
+        const error = new Error(`Structural-quality provider ${id} must be an object or factory`);
+        error.code = "E_STRUCTURAL_QUALITY_PROVIDER_INVALID";
+        throw error;
+      }
+      providers[id] = provider;
+    }
+    context.structuralQualityProviders = Object.freeze(providers);
+  }
+  if (options?.advisoryContextProviders !== undefined) {
+    const configured = options.advisoryContextProviders instanceof Map
+      ? Object.fromEntries(options.advisoryContextProviders.entries())
+      : options.advisoryContextProviders;
+    if (!configured || typeof configured !== "object" || Array.isArray(configured)) {
+      const error = new Error("advisoryContextProviders must be an object or Map");
+      error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+      throw error;
+    }
+    const providers = {};
+    for (const [id, provider] of Object.entries(configured)) {
+      if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) {
+        const error = new Error(`Invalid advisory-context provider ID: ${id}`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function"
+        && (!provider || typeof provider !== "object" || Array.isArray(provider))) {
+        const error = new Error(`Advisory-context provider ${id} must be an object or factory`);
+        error.code = E_ADVISORY_CONTEXT_PROVIDER_INVALID;
+        throw error;
+      }
+      if (typeof provider !== "function") {
+        assertAdvisoryContextProviderIdentity(provider, id);
+      }
+      providers[id] = provider;
+    }
+    context.advisoryContextProviders = Object.freeze(providers);
+  }
   return Object.freeze(context);
 }

package/src/core/schema-validation.js

@@ -54,6 +54,7 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "execution-profile-benchmark-scenario",
   "execution-profile-benchmark-run",
   "execution-profile-benchmark-aggregate",
+  "structural-quality",
 ]);
 
 export class SchemaValidationError extends Error {