@cassiomc1/forgeloop 1.8.1 → 1.10.0

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/continuity-lint.js

@@ -0,0 +1,89 @@
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+
+function finding(code, severity, field, itemId = null) {
+  return { code, severity, field, itemId };
+}
+
+function hasOperationalHints(continuity) {
+  return Boolean(
+    continuity.currentFocus
+    || continuity.remainingWork?.length
+    || continuity.knownIssues?.length
+    || continuity.changedAreas?.length
+    || continuity.inspectFirst?.length
+    || (typeof continuity.resumeNote === "string" && continuity.resumeNote.trim() !== ""),
+  );
+}
+
+export async function lintContinuity({ target, continuity, state } = {}) {
+  const findings = [];
+  if (!continuity || typeof continuity !== "object" || Array.isArray(continuity)) {
+    return { status: "PASS", findings };
+  }
+
+  const completedSteps = new Set(
+    Array.isArray(state?.completedSteps) ? state.completedSteps : [],
+  );
+
+  for (const [index, item] of (continuity.remainingWork ?? []).entries()) {
+    if (!item?.id) continue;
+    if (completedSteps.has(item.id)) {
+      findings.push(finding(
+        "CONTINUITY_REMAINING_ALREADY_COMPLETED",
+        "WARN",
+        `remainingWork[${index}]`,
+        item.id,
+      ));
+    }
+  }
+
+  if (continuity.currentFocus?.id && completedSteps.has(continuity.currentFocus.id)) {
+    findings.push(finding(
+      "CONTINUITY_FOCUS_ALREADY_COMPLETED",
+      "WARN",
+      "currentFocus",
+      continuity.currentFocus.id,
+    ));
+  }
+
+  const knownIssueIds = new Set(
+    (continuity.knownIssues ?? []).map((item) => item?.id).filter(Boolean),
+  );
+  for (const [index, item] of (continuity.remainingWork ?? []).entries()) {
+    if (item?.id && knownIssueIds.has(item.id)) {
+      findings.push(finding(
+        "CONTINUITY_ITEM_ROLE_CONFLICT",
+        "WARN",
+        `remainingWork[${index}]`,
+        item.id,
+      ));
+    }
+  }
+
+  if (typeof target === "string" && target.trim() !== "") {
+    for (const [index, inspectPath] of (continuity.inspectFirst ?? []).entries()) {
+      try {
+        await assertSafePath(target, inspectPath);
+        if (!(await fileExists(ensureWithin(target, inspectPath)))) {
+          findings.push(finding(
+            "CONTINUITY_INSPECT_PATH_MISSING",
+            "WARN",
+            `inspectFirst[${index}]`,
+          ));
+        }
+      } catch {
+        // Invalid or unsafe paths are rejected by continuity schema validation;
+        // lint never resolves an unchecked path or turns it into authority.
+      }
+    }
+  }
+
+  if (!hasOperationalHints(continuity)) {
+    findings.push(finding("CONTINUITY_EMPTY_HINT_SET", "INFO", "continuity"));
+  }
+
+  return {
+    status: findings.some((item) => item.severity === "WARN") ? "WARN" : "PASS",
+    findings,
+  };
+}

package/src/core/continuity-reconciliation.js

@@ -1,6 +1,7 @@
 import { canonicalFingerprint } from "./artifacts.js";
 import { assertContinuitySemantics, readContinuity } from "./continuity.js";
 import { WORK_TRANSITIONS } from "./protocol.js";
+import { lintContinuity } from "./continuity-lint.js";
 
 const RECONCILIATION_CODE = "E_CONTINUITY_RECONCILIATION_REQUIRED";
 
@@ -188,6 +189,7 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
         path: ".forgeloop/continuity.json",
         present: false,
         latestHandoff,
+        lint: { status: "PASS", findings: [] },
         diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
       };
     }
@@ -200,6 +202,15 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
       present: true,
       error: error.message,
       latestHandoff,
+      lint: {
+        status: "WARN",
+        findings: [{
+          code: error.code ?? "CONTINUITY_INVALID",
+          severity: "WARN",
+          field: "continuity",
+          itemId: null,
+        }],
+      },
     };
   }
 
@@ -229,6 +240,11 @@ export async function reconcileContinuity({ target, packageRoot, taskId = null }
     fingerprint: continuityArtifact.fingerprint,
     continuity: continuityArtifact.value,
     latestHandoff,
+    lint: await lintContinuity({
+      target,
+      continuity: continuityArtifact.value,
+      state,
+    }),
     diagnosticContext: await deriveDiagnosticContextSafe({ target, packageRoot, state }),
   };
 }

package/src/core/continuity.js

@@ -9,7 +9,7 @@ import {
 } from "./artifacts.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
 import { PROTOCOL_VERSION, WORK_PHASES } from "./protocol.js";
-import { assertSecretFree } from "./receipt.js";
+import { normalizePortableText, assertPortableContextSafe } from "./portable-context.js";
 import { getPackageRoot } from "./templates.js";
 import { taskArtifactPath } from "./task-paths.js";
 
@@ -37,16 +37,11 @@ function continuityError(code, message, artifacts = [CONTINUITY_PATH]) {
 }
 
 function nonEmptyString(value, label, maxLength) {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} must be a non-empty string`);
+  try {
+    return normalizePortableText(value, { label, maxLength });
+  } catch (error) {
+    throw continuityError("E_CONTINUITY_INVALID", error.message);
   }
-  if (value.length > maxLength) {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} exceeds the ${maxLength}-character limit`);
-  }
-  if (/\p{Cc}/u.test(value)) {
-    throw continuityError("E_CONTINUITY_INVALID", `${label} contains control characters`);
-  }
-  return value;
 }
 
 function fingerprint(value, label) {
@@ -171,7 +166,11 @@ export function assertContinuitySemantics(input) {
       ? { resumeNote: nonEmptyString(input.resumeNote, "resumeNote", LIMITS.resumeNote) }
       : {}),
   };
-  assertSecretFree(normalized);
+  try {
+    assertPortableContextSafe(normalized);
+  } catch (error) {
+    throw continuityError("E_CONTINUITY_INVALID", error.message);
+  }
   return normalized;
 }
 

package/src/core/error-codes.js

@@ -83,6 +83,70 @@ 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";
+
+export const E_ADVISORY_CONTEXT_PROVIDER_INVALID = "E_ADVISORY_CONTEXT_PROVIDER_INVALID";
+export const E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE = "E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE";
+export const E_ADVISORY_CONTEXT_QUERY_INVALID = "E_ADVISORY_CONTEXT_QUERY_INVALID";
+export const E_ADVISORY_CONTEXT_REQUEST_INVALID = "E_ADVISORY_CONTEXT_REQUEST_INVALID";
+export const E_ADVISORY_CONTEXT_RESULT_INVALID = "E_ADVISORY_CONTEXT_RESULT_INVALID";
+export const E_ADVISORY_CONTEXT_TIMEOUT = "E_ADVISORY_CONTEXT_TIMEOUT";
+export const E_ADVISORY_CONTEXT_OUTPUT_LIMIT = "E_ADVISORY_CONTEXT_OUTPUT_LIMIT";
+export const E_PORTABLE_CONTEXT_INVALID = "E_PORTABLE_CONTEXT_INVALID";
+export const E_HANDOFF_ACCEPTANCE_UNBOUND = "E_HANDOFF_ACCEPTANCE_UNBOUND";
+export const E_HANDOFF_STALE = "E_HANDOFF_STALE";
+export const E_HANDOFF_ALREADY_ACCEPTED = "E_HANDOFF_ALREADY_ACCEPTED";
+export const E_HANDOFF_ACCEPTANCE_INCONSISTENT = "E_HANDOFF_ACCEPTANCE_INCONSISTENT";
+
+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,
@@ -222,11 +286,100 @@ export const E_APPROVAL_ALREADY_RESOLVED = "E_APPROVAL_ALREADY_RESOLVED";
 export const E_TRAJECTORY_SCENARIO_INVALID = "E_TRAJECTORY_SCENARIO_INVALID";
 export const E_TRAJECTORY_REFERENCE_REQUIRED = "E_TRAJECTORY_REFERENCE_REQUIRED";
 
+const ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA = Object.freeze(Object.fromEntries([
+  [E_ADVISORY_CONTEXT_PROVIDER_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context provider configuration or interface implementation is invalid.",
+    safeResolution: "Use a provider implementing id, recall(input) with bounded query parameters; advisory context is optional.",
+  })],
+  [E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, Object.freeze({
+    code: E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Requested advisory context provider is not registered in runtime context.",
+    safeResolution: "Register the provider in runtime context before recall, or proceed without advisory context; provider failure never blocks canonical lifecycle.",
+  })],
+  [E_ADVISORY_CONTEXT_QUERY_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_QUERY_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context query failed portable-context validation or exceeded budget.",
+    safeResolution: "Provide a bounded query free of control characters and secret-like values.",
+  })],
+  [E_ADVISORY_CONTEXT_REQUEST_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_REQUEST_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context recall budgets are not finite integer values within the supported request contract.",
+    safeResolution: "Provide finite integer limit, maxItemChars, maxTotalChars, and timeoutMs values; oversized valid values are clamped to documented maxima.",
+  })],
+  [E_ADVISORY_CONTEXT_RESULT_INVALID, Object.freeze({
+    code: E_ADVISORY_CONTEXT_RESULT_INVALID,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context provider returned an invalid result structure.",
+    safeResolution: "Ensure provider returns items with string summary and optional title, sourceRef, observedAt, confidence.",
+  })],
+  [E_ADVISORY_CONTEXT_TIMEOUT, Object.freeze({
+    code: E_ADVISORY_CONTEXT_TIMEOUT,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context recall exceeded its execution timeout.",
+    safeResolution: "Use a responsive provider or increase timeout within limits; advisory context is optional.",
+  })],
+  [E_ADVISORY_CONTEXT_OUTPUT_LIMIT, Object.freeze({
+    code: E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+    category: "advisory-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Advisory context output exceeded the configured character or item limit.",
+    safeResolution: "Reduce query scope, limit items, or truncate oversized summaries at the provider.",
+  })],
+  [E_PORTABLE_CONTEXT_INVALID, Object.freeze({
+    code: E_PORTABLE_CONTEXT_INVALID,
+    category: "portable-context",
+    classification: "PUBLIC_STABLE",
+    meaning: "Text or object failed portable-context safety, character, or secret limits.",
+    safeResolution: "Ensure text is bounded, contains no control characters, and contains no secret-like values.",
+  })],
+  [E_HANDOFF_ACCEPTANCE_UNBOUND, Object.freeze({
+    code: E_HANDOFF_ACCEPTANCE_UNBOUND,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff snapshot lacks required workStateFingerprint binding.",
+    safeResolution: "Create a fresh handoff from the current ForgeLoop version before accepting it.",
+  })],
+  [E_HANDOFF_STALE, Object.freeze({
+    code: E_HANDOFF_STALE,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff snapshot has drifted from the current canonical task state or repository.",
+    safeResolution: "Create a new fresh handoff from the current task state instead of accepting a stale snapshot.",
+  })],
+  [E_HANDOFF_ALREADY_ACCEPTED, Object.freeze({
+    code: E_HANDOFF_ALREADY_ACCEPTED,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff was already accepted by a different consumer.",
+    safeResolution: "Create a new handoff for the new consumer; do not manually edit acceptance events.",
+  })],
+  [E_HANDOFF_ACCEPTANCE_INCONSISTENT, Object.freeze({
+    code: E_HANDOFF_ACCEPTANCE_INCONSISTENT,
+    category: "handoff",
+    classification: "PUBLIC_STABLE",
+    meaning: "Handoff acceptance disagrees with task event ledger history.",
+    safeResolution: "Verify ledger integrity and require a preceding valid HANDOFF_CREATED event.",
+  })],
+]));
+
 /**
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
 export const PUBLIC_ERROR_CODES = Object.freeze({
   ...EXTENSION_PUBLIC_ERROR_CODES,
+  ...STRUCTURAL_QUALITY_ERROR_METADATA,
+  ...ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA,
   E_PREFLIGHT_NOT_READY: Object.freeze({
     code: "E_PREFLIGHT_NOT_READY",
     category: "preflight",
@@ -1044,6 +1197,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,
@@ -1132,6 +1306,18 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_FAILURE_SIGNATURE_INVALID,
   E_STRATEGY_OSCILLATION,
   "E_TRACE_SNAPSHOT_INCONSISTENT",
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_QUERY_INVALID,
+  E_ADVISORY_CONTEXT_REQUEST_INVALID,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_PORTABLE_CONTEXT_INVALID,
+  E_HANDOFF_ACCEPTANCE_UNBOUND,
+  E_HANDOFF_STALE,
+  E_HANDOFF_ALREADY_ACCEPTED,
+  E_HANDOFF_ACCEPTANCE_INCONSISTENT,
 ]));
 
 /**

package/src/core/events.js

@@ -160,6 +160,16 @@ export function validateKnownEventDetails(event) {
       }
       assertFingerprint(event.details.digest, "HANDOFF_CREATED details.digest");
       return;
+    case "HANDOFF_ACCEPTED":
+      if (!event.details || typeof event.details !== "object" || Array.isArray(event.details)
+        || typeof event.details.handoffId !== "string" || !/^handoff-[A-Za-z0-9_-]+$/.test(event.details.handoffId)
+        || typeof event.details.handoffDigest !== "string"
+        || typeof event.details.consumerId !== "string" || !event.details.consumerId.trim()
+        || (event.details.harness !== undefined && (typeof event.details.harness !== "string" || !event.details.harness.trim()))) {
+        throw protocolError("E_EVENT_INVALID", "HANDOFF_ACCEPTED requires a valid handoffId, handoffDigest, and consumerId");
+      }
+      assertFingerprint(event.details.handoffDigest, "HANDOFF_ACCEPTED details.handoffDigest");
+      return;
     case "RESPONSIBILITY_SET":
       assertStructuredArtifactEvent(event, ["responsibilityFingerprint"], "RESPONSIBILITY_SET");
       if (typeof event.details.label !== "string" || !event.details.label) {
@@ -513,6 +523,8 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
   const seen = new Set();
   let lastMilestone = -1;
   const milestoneCounts = new Map();
+  const createdHandoffs = new Map();
+  const acceptedHandoffs = new Set();
   for (const [index, event] of events.entries()) {
     if (event.seq !== index + 1) {
       errors.push({ code: "E_EVENT_INVALID", message: `event sequence must be ${index + 1}` });
@@ -584,6 +596,26 @@ export async function validateEventLedger(target, packageRoot, options = {}) {
     if (event.event === "COMPLETION_REJECTED" && !seen.has("VERIFICATION_STARTED")) {
       errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion rejected before verification started" });
     }
+    if (event.event === "HANDOFF_CREATED") {
+      if (event.details?.handoffId) {
+        createdHandoffs.set(event.details.handoffId, event.details.digest);
+      }
+    }
+    if (event.event === "HANDOFF_ACCEPTED") {
+      const hId = event.details?.handoffId;
+      if (hId) {
+        if (acceptedHandoffs.has(hId)) {
+          errors.push({ code: "E_HANDOFF_ALREADY_ACCEPTED", message: `duplicate HANDOFF_ACCEPTED for handoffId ${hId}` });
+        } else {
+          acceptedHandoffs.add(hId);
+          if (!createdHandoffs.has(hId)) {
+            errors.push({ code: "E_HANDOFF_ACCEPTANCE_INCONSISTENT", message: `HANDOFF_ACCEPTED has no preceding HANDOFF_CREATED for handoffId ${hId}` });
+          } else if (createdHandoffs.get(hId) !== event.details?.handoffDigest) {
+            errors.push({ code: "E_HANDOFF_ACCEPTANCE_INCONSISTENT", message: `HANDOFF_ACCEPTED digest mismatch for handoffId ${hId}` });
+          }
+        }
+      }
+    }
   }
   validateLegacyRecoveryMigrations(events, errors, {
     allowUnmigratedLegacyRecoveryEvents: options?.allowUnmigratedLegacyRecoveryEvents === true,

package/src/core/execution-profile-context.js

@@ -112,6 +112,7 @@ export function projectExecutionProfileContext({
   route,
   state,
   nextAction,
+  runtimeContext,
 } = {}) {
   if (typeof taskId !== "string" || !taskId) throw contextError("E_TASK_REQUIRED", "taskId is required");
   if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
@@ -126,6 +127,18 @@ export function projectExecutionProfileContext({
   const profile = route.executionProfile ? assertExecutionProfile(route.executionProfile) : legacyExecutionProfile();
   const resolvedProfile = profile.resolved;
   const policy = getExecutionProfileContextPolicy(resolvedProfile);
+  const available = [...OPTIONAL_CONTEXT_BY_PROFILE[resolvedProfile]];
+  const advisoryProviders = runtimeContext?.advisoryContextProviders;
+  const hasAdvisory = Boolean(
+    advisoryProviders && (
+      advisoryProviders instanceof Map
+        ? advisoryProviders.size > 0
+        : Object.keys(advisoryProviders).length > 0
+    ),
+  );
+  if (hasAdvisory && !available.includes("advisory-context")) {
+    available.push("advisory-context");
+  }
   return {
     schemaVersion: 1,
     protocolVersion: 1,
@@ -140,7 +153,7 @@ export function projectExecutionProfileContext({
     verificationRequirements: verificationRequirements(contract),
     contextPolicy: policy,
     optionalContext: {
-      available: [...OPTIONAL_CONTEXT_BY_PROFILE[resolvedProfile]],
+      available,
       loaded: [],
     },
     invariants: { ...PROFILE_INVARIANTS },
@@ -173,5 +186,6 @@ export async function buildExecutionProfileContext({
     route: routeArtifact.value,
     state,
     nextAction,
+    runtimeContext,
   });
 }

package/src/core/filesystem.js

@@ -73,6 +73,38 @@ export function ensureWithin(root, relativePath) {
   return path.join(root, normalized);
 }
 
+function normalizeWindowsPathForComparison(value) {
+  const lowerValue = value.toLowerCase();
+  let normalized = value;
+  if (lowerValue.startsWith("\\\\?\\unc\\")) {
+    normalized = `\\\\${value.slice(8)}`;
+  } else if (lowerValue.startsWith("\\\\.\\unc\\")) {
+    normalized = `\\\\${value.slice(8)}`;
+  } else if (lowerValue.startsWith("\\\\?\\")) {
+    normalized = value.slice(4);
+  } else if (lowerValue.startsWith("\\\\.\\")) {
+    normalized = value.slice(4);
+  }
+  return path.win32.normalize(normalized).toLowerCase();
+}
+
+export function isPathWithin(root, candidate, { platform = process.platform } = {}) {
+  const pathApi = platform === "win32" ? path.win32 : path;
+  const normalizeForComparison = (value) => {
+    return platform === "win32"
+      ? normalizeWindowsPathForComparison(value)
+      : pathApi.normalize(value);
+  };
+  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 +137,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 +217,4 @@ export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {})
     }
     throw error;
   }
-}
+}