@cassiomc1/forgeloop 1.6.5 → 1.8.0

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

@@ -0,0 +1,177 @@
+import { readContract } from "./contract.js";
+import { assertExecutionProfile, LEGACY_EXECUTION_PROFILE } from "./execution-profile.js";
+import { getNextAction } from "./next-action.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+
+export const PROFILE_CONTEXT_POLICIES = Object.freeze({
+  light: Object.freeze({
+    contextDepth: "targeted",
+    output: "compact",
+    planDepth: "short",
+    guideStrategy: "targeted",
+    verificationStrategy: "focused",
+    optionalArtifacts: "lazy",
+    requiredSections: ["objective", "scope", "implementation", "verification"],
+    excludedContext: ["full-history", "full-trace", "all-schemas", "all-guides", "reflection", "unrelated-repository-context"],
+  }),
+  balanced: Object.freeze({
+    contextDepth: "relevant",
+    output: "standard",
+    planDepth: "standard",
+    guideStrategy: "relevant",
+    verificationStrategy: "normal",
+    optionalArtifacts: "lazy",
+    requiredSections: ["objective", "scope", "implementation", "verification", "relevant-history"],
+    excludedContext: ["unrelated-repository-context"],
+  }),
+  full: Object.freeze({
+    contextDepth: "expanded",
+    output: "expanded",
+    planDepth: "deep",
+    guideStrategy: "broad-risk",
+    verificationStrategy: "expanded-when-justified",
+    optionalArtifacts: "when-required-or-useful",
+    requiredSections: ["objective", "scope", "implementation", "verification", "risk", "relevant-history"],
+    excludedContext: [],
+  }),
+});
+
+const OPTIONAL_CONTEXT_BY_PROFILE = Object.freeze({
+  light: Object.freeze([]),
+  balanced: Object.freeze(["task-history", "relevant-artifacts"]),
+  full: Object.freeze([
+    "task-history",
+    "relevant-artifacts",
+    "risk-context",
+    "dependency-context",
+    "review-context",
+    "verification-context",
+  ]),
+});
+
+const PROFILE_INVARIANTS = Object.freeze({
+  lifecyclePhasesPreserved: true,
+  requiredGatesPreserved: true,
+  evidenceRequirementsPreserved: true,
+  verificationTruthPreserved: true,
+  authorityChecksPreserved: true,
+  provenancePreserved: true,
+  completionValidationPreserved: true,
+  safetyFloorPreserved: true,
+  lifecyclePhaseSkippingAllowed: false,
+});
+
+function contextError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function legacyExecutionProfile() {
+  return {
+    requested: LEGACY_EXECUTION_PROFILE,
+    floor: LEGACY_EXECUTION_PROFILE,
+    resolved: LEGACY_EXECUTION_PROFILE,
+    reasons: ["LEGACY_ROUTE_COMPATIBILITY"],
+    escalated: false,
+  };
+}
+
+export function getExecutionProfileContextPolicy(profile) {
+  if (!Object.prototype.hasOwnProperty.call(PROFILE_CONTEXT_POLICIES, profile)) {
+    throw contextError("E_EXECUTION_PROFILE_INVALID", `Unsupported resolved execution profile: ${profile}`);
+  }
+  return {
+    ...PROFILE_CONTEXT_POLICIES[profile],
+    allowedOptionalContext: [...OPTIONAL_CONTEXT_BY_PROFILE[profile]],
+  };
+}
+
+function verificationRequirements(contract) {
+  if (Array.isArray(contract.verification)) {
+    return contract.verification.map((requirement) => {
+      if (typeof requirement === "string") return { id: requirement, text: requirement, type: "VERIFICATION" };
+      return {
+        id: requirement.id ?? null,
+        text: requirement.text ?? null,
+        type: requirement.type ?? "VERIFICATION",
+      };
+    });
+  }
+  return (contract.successCriteria ?? []).map((criterion, index) => ({
+    id: `success-criterion-${index + 1}`,
+    text: criterion,
+    type: "SUCCESS_CRITERION",
+  }));
+}
+
+export function projectExecutionProfileContext({
+  taskId,
+  contract,
+  route,
+  state,
+  nextAction,
+} = {}) {
+  if (typeof taskId !== "string" || !taskId) throw contextError("E_TASK_REQUIRED", "taskId is required");
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) {
+    throw contextError("E_EXECUTION_PROFILE_CONTEXT_INVALID", "contract is required for profile-aware context");
+  }
+  if (!route || typeof route !== "object" || Array.isArray(route)) {
+    throw contextError("E_EXECUTION_PROFILE_CONTEXT_INVALID", "route is required for profile-aware context");
+  }
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw contextError("E_EXECUTION_PROFILE_CONTEXT_INVALID", "work state is required for profile-aware context");
+  }
+  const profile = route.executionProfile ? assertExecutionProfile(route.executionProfile) : legacyExecutionProfile();
+  const resolvedProfile = profile.resolved;
+  const policy = getExecutionProfileContextPolicy(resolvedProfile);
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    executionProfile: profile,
+    phase: state.phase,
+    nextAction: nextAction?.nextAction ?? null,
+    objective: contract.objective ?? null,
+    deliverables: [...(contract.deliverables ?? [])],
+    constraints: [...(contract.constraints ?? [])],
+    selectedGuideIds: [...(state.selectedGuides ?? [])],
+    verificationRequirements: verificationRequirements(contract),
+    contextPolicy: policy,
+    optionalContext: {
+      available: [...OPTIONAL_CONTEXT_BY_PROFILE[resolvedProfile]],
+      loaded: [],
+    },
+    invariants: { ...PROFILE_INVARIANTS },
+  };
+}
+
+export async function buildExecutionProfileContext({
+  target,
+  packageRoot,
+  taskId,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  if (typeof taskId !== "string" || !taskId) throw contextError("E_TASK_REQUIRED", "taskId is required");
+  const [contractArtifact, routeArtifact, state] = await Promise.all([
+    readContract(target, packageRoot, { taskId }),
+    readPersistedRoute(target, packageRoot, { taskId }),
+    readWorkState(target, { packageRoot, taskId }),
+  ]);
+  const nextAction = await getNextAction({
+    target,
+    packageRoot,
+    taskId,
+    authorityContext,
+    runtimeContext,
+  });
+  return projectExecutionProfileContext({
+    taskId,
+    contract: contractArtifact.value,
+    route: routeArtifact.value,
+    state,
+    nextAction,
+  });
+}

package/src/core/execution-profile.js

@@ -0,0 +1,248 @@
+/**
+ * Deterministic execution-profile selection.
+ *
+ * Profiles are an efficiency and guidance dimension only. They do not alter
+ * compliance mode, lifecycle transitions, evidence requirements, authority,
+ * or completion validation. A safety floor always wins over an explicit
+ * lower request.
+ */
+
+export const EXECUTION_PROFILES = Object.freeze(["light", "balanced", "full"]);
+export const EXECUTION_PROFILE_REQUESTS = Object.freeze(["auto", ...EXECUTION_PROFILES]);
+export const LEGACY_EXECUTION_PROFILE = "balanced";
+
+const PROFILE_RANK = Object.freeze({ light: 0, balanced: 1, full: 2 });
+const FULL_WORK_TYPES = new Set(["infrastructure", "security-review", "release", "api-auth"]);
+const BALANCED_WORK_TYPES = new Set([
+  "code", "bug", "refactor", "backend", "api", "dependency-update", "performance", "accessibility",
+]);
+const FULL_SURFACES = new Set(["auth", "critical-path"]);
+const BALANCED_SURFACES = new Set(["data", "database", "ci", "config"]);
+const FULL_RISKS = new Set([
+  "secrets", "personal-data", "publication", "critical-path", "destructive", "irreversible",
+  "production-deployment", "credentials", "payment", "migration",
+]);
+const BALANCED_RISKS = new Set(["untrusted-input", "performance", "accessibility", "external-service"]);
+
+function profileError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function normalizeRequestedProfile(value, label) {
+  const normalized = value ?? "auto";
+  if (typeof normalized !== "string" || !EXECUTION_PROFILE_REQUESTS.includes(normalized)) {
+    throw profileError("E_EXECUTION_PROFILE_INVALID", `${label} must be one of ${EXECUTION_PROFILE_REQUESTS.join(", ")}`);
+  }
+  return normalized;
+}
+
+function uniqueReasons(reasons) {
+  return [...new Set(reasons.filter((reason) => typeof reason === "string" && reason))];
+}
+
+function normalizedRouteInput(routeInput = {}) {
+  return {
+    workType: typeof routeInput.workType === "string" ? routeInput.workType : null,
+    surfaces: Array.isArray(routeInput.surfaces) ? [...routeInput.surfaces] : [],
+    risks: Array.isArray(routeInput.risks) ? [...routeInput.risks] : [],
+    platforms: Array.isArray(routeInput.platforms) ? [...routeInput.platforms] : [],
+    behaviorChange: routeInput.behaviorChange === true,
+    executableChange: routeInput.executableChange === true,
+  };
+}
+
+function contractCollections(contract) {
+  const source = contract && typeof contract === "object" && !Array.isArray(contract) ? contract : {};
+  return {
+    deliverables: Array.isArray(source.deliverables) ? source.deliverables : [],
+    successCriteria: Array.isArray(source.successCriteria) ? source.successCriteria : [],
+    risks: Array.isArray(source.risks) ? source.risks : [],
+    constraints: Array.isArray(source.constraints) ? source.constraints : [],
+    stopConditions: Array.isArray(source.stopConditions) ? source.stopConditions : [],
+  };
+}
+
+function contractSignals(contract) {
+  const collections = contractCollections(contract);
+  const riskText = collections.risks.join(" ").toLowerCase();
+  const allText = [
+    ...collections.deliverables,
+    ...collections.successCriteria,
+    ...collections.constraints,
+    ...collections.stopConditions,
+  ].join(" ").toLowerCase();
+  const combinedText = `${riskText} ${allText}`;
+  const signals = {
+    secrets: /\bsecrets?\b|\bcredentials?\b|\bpasswords?\b|\bprivate keys?\b/.test(combinedText),
+    personalData: /\bpersonal[- ]data\b|\bpii\b|\bsensitive data\b/.test(combinedText),
+    publication: /\bpublication\b|\bpublish(?:ing|ed)?\b|\bdeploy(?:ment|ed)?\b/.test(combinedText),
+    destructive: /\bdestructive\b|\birreversible\b|\bdrop database\b|\bdelete production\b/.test(combinedText),
+    migration: /\bmigration\b|\bmigrate\b|\bschema change\b|\birreversible persistence\b/.test(combinedText),
+    payment: /\bpayments?\b|\bcheckout\b|\bbilling\b/.test(combinedText),
+    externalMutation: /\bexternal mutation\b|\bmutate(?:s|d)? external\b|\bpublish(?:ing|ed)?\b/.test(combinedText),
+    authoritySensitiveExternalMutation: /\bauthority[- ]sensitive\b|\bhost[- ]authorized external\b|\bexternal mutation requiring authority\b/.test(combinedText),
+    broadProductionValidation: /\bbroad production validation\b|\bproduction validation\b|\bvalidate in production\b/.test(combinedText),
+  };
+  return signals;
+}
+
+function scopeSignals({ routeInput, contract, taskDescriptor }) {
+  const collections = contractCollections(contract);
+  const claims = Array.isArray(taskDescriptor?.writeClaims) ? taskDescriptor.writeClaims : [];
+  const deliverableCount = collections.deliverables.length;
+  const claimCount = claims.length;
+  const successCriteriaCount = collections.successCriteria.length;
+  const executableSurfaceCount = new Set([
+    ...(routeInput.surfaces ?? []),
+    ...(routeInput.platforms ?? []),
+  ]).size;
+  return {
+    multiDeliverable: deliverableCount > 4,
+    multiClaim: claimCount > 4,
+    broad: successCriteriaCount > 6,
+    multiSurfaceExecutableChange: (routeInput.behaviorChange || routeInput.executableChange)
+      && executableSurfaceCount > 1,
+  };
+}
+
+function assertResolvedProfile(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile must be an object");
+  }
+  if (!EXECUTION_PROFILE_REQUESTS.includes(value.requested)
+    || !EXECUTION_PROFILES.includes(value.floor)
+    || !EXECUTION_PROFILES.includes(value.resolved)) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile contains an unsupported profile value");
+  }
+  if (!Array.isArray(value.reasons) || value.reasons.length === 0
+    || value.reasons.some((reason) => typeof reason !== "string" || !reason)) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile.reasons must be a non-empty string array");
+  }
+  if (new Set(value.reasons).size !== value.reasons.length) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile.reasons must not contain duplicates");
+  }
+  if (typeof value.escalated !== "boolean") {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile.escalated must be boolean");
+  }
+  if (PROFILE_RANK[value.resolved] < PROFILE_RANK[value.floor]) {
+    throw profileError("E_EXECUTION_PROFILE_SAFETY_FLOOR_INVALID", "executionProfile.resolved cannot be below its safety floor");
+  }
+  if (value.requested !== "auto" && PROFILE_RANK[value.resolved] < PROFILE_RANK[value.requested]) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile.resolved cannot be below its explicit request");
+  }
+  const expectedEscalated = value.requested !== "auto"
+    && PROFILE_RANK[value.requested] < PROFILE_RANK[value.floor];
+  if (value.escalated !== expectedEscalated) {
+    throw profileError("E_EXECUTION_PROFILE_INCONSISTENT", "executionProfile.escalated does not match the requested profile and safety floor");
+  }
+  return value;
+}
+
+export function assertExecutionProfile(value) {
+  return assertResolvedProfile(value);
+}
+
+export function projectExecutionProfile(route) {
+  if (!route || typeof route !== "object") return null;
+  return route.executionProfile?.resolved ?? LEGACY_EXECUTION_PROFILE;
+}
+
+export function resolveExecutionProfile({
+  routeInput = {},
+  contract = null,
+  taskDescriptor = null,
+  configuredProfile = "auto",
+  requestedProfile = null,
+} = {}) {
+  const normalizedRoute = normalizedRouteInput(routeInput);
+  const configured = normalizeRequestedProfile(configuredProfile, "configuredProfile");
+  const requested = requestedProfile === null || requestedProfile === undefined
+    ? configured
+    : normalizeRequestedProfile(requestedProfile, "requestedProfile");
+  const reasons = [];
+
+  if (requestedProfile !== null && requestedProfile !== undefined) reasons.push("PROFILE_EXPLICIT_REQUEST");
+  else if (configured !== "auto") reasons.push("PROFILE_PROJECT_CONFIG");
+  else reasons.push("PROFILE_DEFAULT_AUTO");
+
+  let floor = "light";
+  const fullReasons = [];
+  const balancedReasons = [];
+  const addFull = (reason) => fullReasons.push(reason);
+  const addBalanced = (reason) => balancedReasons.push(reason);
+
+  if (FULL_WORK_TYPES.has(normalizedRoute.workType)) {
+    addFull(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  }
+  if (BALANCED_WORK_TYPES.has(normalizedRoute.workType)) {
+    addBalanced(`WORK_${normalizedRoute.workType.toUpperCase().replaceAll("-", "_")}`);
+  }
+  for (const surface of normalizedRoute.surfaces) {
+    if (FULL_SURFACES.has(surface)) addFull(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_SURFACES.has(surface)) addBalanced(`SURFACE_${surface.toUpperCase().replaceAll("-", "_")}`);
+  }
+  for (const risk of normalizedRoute.risks) {
+    if (FULL_RISKS.has(risk)) addFull(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+    else if (BALANCED_RISKS.has(risk)) addBalanced(`RISK_${risk.toUpperCase().replaceAll("-", "_")}`);
+  }
+  if (normalizedRoute.behaviorChange) addBalanced("WORK_BEHAVIOR_CHANGE");
+  if (normalizedRoute.executableChange) addBalanced("WORK_EXECUTABLE_CHANGE");
+
+  const textSignals = contractSignals(contract);
+  if (textSignals.secrets) addFull("RISK_SECRETS");
+  if (textSignals.personalData) addFull("RISK_PERSONAL_DATA");
+  if (textSignals.publication) addFull("RISK_PUBLICATION");
+  if (textSignals.destructive) addFull("RISK_DESTRUCTIVE");
+  if (textSignals.migration && normalizedRoute.surfaces.includes("database")) addFull("RISK_MIGRATION");
+  if (textSignals.payment) addFull("RISK_PAYMENT");
+  if (textSignals.externalMutation) addFull("RISK_EXTERNAL_MUTATION");
+  if (textSignals.authoritySensitiveExternalMutation) addFull("RISK_AUTHORITY_SENSITIVE_EXTERNAL_MUTATION");
+  if (textSignals.broadProductionValidation) addFull("RISK_PRODUCTION_VALIDATION");
+
+  const scope = scopeSignals({ routeInput: normalizedRoute, contract, taskDescriptor });
+  if (scope.multiDeliverable) addBalanced("SCOPE_MULTI_DELIVERABLE");
+  if (scope.multiClaim) addBalanced("SCOPE_MULTI_CLAIM");
+  if (scope.broad || scope.multiSurfaceExecutableChange) addBalanced("SCOPE_BROAD");
+
+  if (fullReasons.length > 0) {
+    floor = "full";
+    reasons.push(...fullReasons);
+  } else if (balancedReasons.length > 0) {
+    floor = "balanced";
+    reasons.push(...balancedReasons);
+  } else {
+    const lowRiskDocumentation = normalizedRoute.workType === "documentation"
+      || normalizedRoute.surfaces.includes("documentation");
+    const lowRiskUi = normalizedRoute.workType === "ui-copy"
+      || normalizedRoute.surfaces.some((surface) => ["ui", "forms", "mobile", "desktop"].includes(surface));
+    reasons.push(lowRiskDocumentation
+      ? "WORK_LOW_RISK_DOCUMENTATION"
+      : lowRiskUi
+        ? "WORK_LOW_RISK_UI"
+        : "NO_ESCALATION_SIGNAL");
+    reasons.push("NO_HIGH_RISK_SIGNAL");
+    reasons.push(scope.broad || scope.multiDeliverable || scope.multiClaim || scope.multiSurfaceExecutableChange
+      ? "SCOPE_BROAD"
+      : "NARROW_DELIVERABLE_SCOPE");
+  }
+
+  if (floor !== "full" && balancedReasons.length > 0 && fullReasons.length === 0) {
+    // Keep scope/risk reasons in the same deterministic order as the inputs.
+    for (const reason of balancedReasons) if (!reasons.includes(reason)) reasons.push(reason);
+  }
+
+  const requestedRank = requested === "auto" ? PROFILE_RANK[floor] : PROFILE_RANK[requested];
+  const resolved = EXECUTION_PROFILES.find((profile) => PROFILE_RANK[profile] === Math.max(requestedRank, PROFILE_RANK[floor]));
+  const escalated = requested !== "auto" && PROFILE_RANK[requested] < PROFILE_RANK[floor];
+  if (escalated) reasons.push("PROFILE_ESCALATED_BY_SAFETY");
+
+  return assertResolvedProfile({
+    requested,
+    floor,
+    resolved,
+    reasons: uniqueReasons(reasons),
+    escalated,
+  });
+}

package/src/core/integration-invocation-policy.js

@@ -29,6 +29,7 @@ const READ_ONLY_COMMANDS = Object.freeze(new Set([
   "inspect", "validate-state", "validate-protocol", "validate-receipt",
   "policy-status", "policy-diff", "rule-verify", "policy",
   "history", "trace", "reflect",
+  "efficiency",
   "workspace-status", "handoff-list", "handoff-show", "responsibility-status",
   "attestation-verify", "attestation-status", "attestation-verify-range",
 ]));
@@ -39,6 +40,7 @@ const LOOP_MUTATION_COMMANDS = Object.freeze(new Set([
   "record-check", "record-diagnosis", "record-decision-criterion",
   "record-terminal-result", "complete",
   "record-intervention", "record-hypothesis-disposition",
+  "usage-record",
   "workspace-bind", "handoff-create", "responsibility-set", "verify-scope", "attestation-create",
 ]));
 
@@ -59,6 +61,8 @@ const STATIC_RISK_CLASSES = Object.freeze({
   eval: INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
   "action-show": INTEGRATION_RISK_CLASSES.READ_ONLY,
   metrics: INTEGRATION_RISK_CLASSES.READ_ONLY,
+  efficiency: INTEGRATION_RISK_CLASSES.READ_ONLY,
+  "usage-record": INTEGRATION_RISK_CLASSES.LOOP_MUTATION,
   init: INTEGRATION_RISK_CLASSES.MAINTENANCE,
   update: INTEGRATION_RISK_CLASSES.MAINTENANCE,
   activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
@@ -137,6 +141,44 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
         readOnlyMetrics: true,
         projectLocalReference: true,
       },
+      adaptiveExecutionProfiles: {
+        version: 1,
+        supported: true,
+        deterministic: true,
+        lifecycleFastPath: false,
+      },
+      executionProfileContext: {
+        version: 1,
+        supported: true,
+        resource: "task/context",
+        resolvedProfileAuthoritative: true,
+        compatibilityFallback: "balanced",
+        lifecycleFastPath: false,
+      },
+      compactLifecycleOutput: {
+        version: 1,
+        supported: true,
+        commands: ["next", "task-show"],
+        preservesDefaultOutput: true,
+      },
+      usageTelemetry: {
+        version: 1,
+        supported: true,
+        estimation: false,
+        evidence: false,
+      },
+      efficiencyMetrics: {
+        version: 1,
+        supported: true,
+        comparativeOnly: true,
+      },
+      contextUsageObservability: {
+        version: 1,
+        supported: true,
+        sources: ["HOST_REPORTED", "UNKNOWN"],
+        estimation: false,
+        inflationStatus: "OBSERVATIONAL",
+      },
       workspaceBinding: {
         version: 1,
         supported: true,
@@ -194,6 +236,7 @@ export function getForgeLoopCapabilities({ packageVersion = null } = {}) {
       { name: "task/action", scope: "TASK" },
       { name: "task/approvals", scope: "TASK" },
       { name: "task/metrics", scope: "TASK" },
+      { name: "task/context", scope: "TASK" },
       { name: "task/evaluations", scope: "TASK" },
       { name: "project/capability-policy", scope: "PROJECT" },
     ],

package/src/core/integration-resources.js

@@ -17,6 +17,7 @@ import { listCanonicalHandoffs } from "./handoff.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
+import { buildExecutionProfileContext } from "./execution-profile-context.js";
 
 /**
  * Canonical integration resource allowlist.
@@ -80,6 +81,7 @@ export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
   "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." }),
   "task/metrics": Object.freeze({ scope: "TASK", description: "Read-only trajectory metrics for one task." }),
+  "task/context": Object.freeze({ scope: "TASK", description: "Read-only profile-aware task context with bounded presentation policy." }),
   "task/evaluations": Object.freeze({ scope: "TASK", description: "Persisted trajectory evaluations for one task." }),
   "project/capability-policy": Object.freeze({ scope: "PROJECT", description: "Project capability policy, never host authority." }),
 });
@@ -104,6 +106,7 @@ export async function readForgeLoopIntegrationResource(uri, {
   packageVersion = null,
   taskId = null,
   actionId = null,
+  runtimeContext = null,
 } = {}) {
   const resource = INTEGRATION_RESOURCE_DEFINITIONS[uri];
   if (!resource) {
@@ -158,6 +161,7 @@ export async function readForgeLoopIntegrationResource(uri, {
     case "task/action":
     case "task/approvals":
     case "task/metrics":
+    case "task/context":
     case "task/evaluations": {
       if (typeof taskId !== "string" || !taskId) {
         const error = new Error(`Resource ${uri} requires a taskId`); error.code = "E_TASK_REQUIRED"; throw error;
@@ -199,7 +203,24 @@ export async function readForgeLoopIntegrationResource(uri, {
     return { uri, taskId, data: { approvals: await listApprovals(projectPath, { packageRoot, taskId }) } };
   }
   if (uri === "task/metrics") {
-    return { uri, taskId, data: await buildTrajectoryMetrics({ target: projectPath, packageRoot, taskId }) };
+    return {
+      uri,
+      taskId,
+      data: await buildTrajectoryMetrics({ target: projectPath, packageRoot, taskId, runtimeContext }),
+    };
+  }
+  if (uri === "task/context") {
+    return {
+      uri,
+      taskId,
+      data: await buildExecutionProfileContext({
+        target: projectPath,
+        packageRoot,
+        taskId,
+        authorityContext: runtimeContext?.authorityContext,
+        runtimeContext,
+      }),
+    };
   }
   if (uri === "task/evaluations") {
     const dir = path.join(projectPath, taskDirectory(taskId), "evaluations");

package/src/core/protocol-info.js

@@ -93,6 +93,48 @@ export function protocolInfo({ packageVersion = null } = {}) {
       capabilityPolicy: { version: 1, supported: true, decisions: ["ALLOW", "DENY", "REQUIRE_AUTHORITY", "REQUIRE_APPROVAL"] },
       durableApprovals: { version: 1, supported: true, fingerprintBound: true, hostAttestationMinting: false },
       trajectoryMetrics: { version: 1, supported: true, usageUnknownWhenUnreported: true, overallScore: false },
+      adaptiveExecutionProfiles: {
+        version: 1,
+        supported: true,
+        requests: ["auto", "light", "balanced", "full"],
+        resolvedProfiles: ["light", "balanced", "full"],
+        deterministic: true,
+        lifecycleFastPath: false,
+      },
+      executionProfileContext: {
+        version: 1,
+        supported: true,
+        resource: "task/context",
+        resolvedProfileAuthoritative: true,
+        compatibilityFallback: "balanced",
+        lifecycleFastPath: false,
+      },
+      compactLifecycleOutput: {
+        version: 1,
+        supported: true,
+        commands: ["next", "task-show"],
+        preservesDefaultOutput: true,
+      },
+      usageTelemetry: {
+        version: 1,
+        supported: true,
+        sources: ["PROVIDER_REPORTED", "HOST_REPORTED", "ACTOR_REPORTED", "UNKNOWN"],
+        estimation: false,
+        evidence: false,
+      },
+      efficiencyMetrics: {
+        version: 1,
+        supported: true,
+        comparativeOnly: true,
+        baseline: "OPTIONAL_PROJECT_LOCAL_JSON",
+      },
+      contextUsageObservability: {
+        version: 1,
+        supported: true,
+        sources: ["HOST_REPORTED", "UNKNOWN"],
+        estimation: false,
+        inflationStatus: "OBSERVATIONAL",
+      },
       trajectoryEvaluation: { version: 1, supported: true, requiresReferenceScenario: true, source: "PROJECT_LOCAL_REFERENCE" },
       workspaceBinding: {
         version: 1,

package/src/core/router.js

@@ -1,4 +1,5 @@
 import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
+import { assertExecutionProfile, resolveExecutionProfile } from "./execution-profile.js";
 
 export const ROUTING_SCHEMA_VERSION = 1;
 
@@ -50,6 +51,12 @@ const SIGNALS = Object.freeze({
     "critical-path",
     "performance",
     "accessibility",
+    "destructive",
+    "irreversible",
+    "production-deployment",
+    "credentials",
+    "payment",
+    "migration",
   ]),
   platforms: new Set(["web", "mobile", "desktop", "server", "ci", "cross-platform"]),
 });
@@ -167,7 +174,7 @@ export function normalizeRouteInput(input = {}) {
   };
 }
 
-export function evaluateRoute(input = {}) {
+export function evaluateRoute(input = {}, profileOptions = {}) {
   const normalized = normalizeRouteInput(input);
   const selected = new Map();
   const excluded = {};
@@ -259,6 +266,14 @@ export function evaluateRoute(input = {}) {
     guides,
     reasons: Object.fromEntries(guides.map((guide) => [guide, selected.get(guide)])),
     excluded,
+    executionProfile: resolveExecutionProfile({
+      routeInput: normalized,
+      contract: profileOptions.contract ?? input.contract ?? null,
+      taskDescriptor: profileOptions.taskDescriptor ?? input.taskDescriptor ?? null,
+      configuredProfile: profileOptions.configuredProfile ?? input.configuredProfile ?? "auto",
+      requestedProfile: profileOptions.requestedProfile
+        ?? (Object.prototype.hasOwnProperty.call(input, "executionProfile") ? input.executionProfile : null),
+    }),
   };
   return assertRouteInvariants(result);
 }
@@ -278,6 +293,13 @@ export function assertRouteInvariants(result) {
   if (result.contractFingerprint !== undefined && !/^[a-f0-9]{64}$/.test(result.contractFingerprint)) {
     throw invariantError("E_ROUTE_INVALID", "Route contractFingerprint must be a lowercase SHA-256 fingerprint");
   }
+  if (result.executionProfile !== undefined) {
+    try {
+      assertExecutionProfile(result.executionProfile);
+    } catch (error) {
+      throw invariantError(error.code ?? "E_EXECUTION_PROFILE_INCONSISTENT", error.message);
+    }
+  }
   for (const guide of result.guides) {
     if (!GUIDE_IDS.includes(guide)) throw invariantError("E_ROUTE_INVALID", `Route result contains unknown guide: ${guide}`);
     if (!Array.isArray(result.reasons?.[guide]) || result.reasons[guide].length === 0) {

package/src/core/runtime-context.js

@@ -94,5 +94,16 @@ export function createForgeLoopContext(options = {}) {
   if (options?.verificationExecutionPolicy !== undefined) {
     context.verificationExecutionPolicy = normalizeVerificationExecutionPolicy(options.verificationExecutionPolicy);
   }
+  if (options?.usageProvider !== undefined) {
+    if (!options.usageProvider
+      || typeof options.usageProvider !== "object"
+      || Array.isArray(options.usageProvider)
+      || typeof options.usageProvider.getTaskUsage !== "function") {
+      const error = new Error("Usage provider must expose getTaskUsage({ projectPath, taskId })");
+      error.code = "E_USAGE_INVALID";
+      throw error;
+    }
+    context.usageProvider = options.usageProvider;
+  }
   return Object.freeze(context);
 }