@cassiomc1/forgeloop 1.6.5 → 1.8.0

package/scripts/summarize-execution-profile-benchmarks.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { aggregateBenchmarkRuns, BENCHMARK_VERSION } from "../src/core/execution-profile-benchmarks.js";
+import { readBenchmarkRunSets, readBenchmarkScenarios } from "./lib/execution-profile-benchmark-io.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const defaultResultsDirectory = path.join(repositoryRoot, "benchmarks", "execution-profiles", "results");
+
+function parseArgs(argv) {
+  const options = { results: defaultResultsDirectory, runSetId: null, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--json") options.json = true;
+    else if (["--results", "--run-set"].includes(argument)) {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) throw new Error(`${argument} requires a value`);
+      if (argument === "--results") options.results = value;
+      else options.runSetId = value;
+    } else if (argument === "--help" || argument === "-h") options.help = true;
+    else throw new Error(`unknown option: ${argument}`);
+  }
+  return options;
+}
+
+function helpText() {
+  return "Usage: npm run benchmark:profiles:summary -- [--results <directory>] [--run-set <id>] [--json]";
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(helpText());
+    return;
+  }
+  const scenarios = await readBenchmarkScenarios(repositoryRoot);
+  const runSets = await readBenchmarkRunSets(path.resolve(options.results), options.runSetId);
+  const summaries = [];
+  for (const runSet of runSets) {
+    const aggregates = scenarios
+      .map((scenario) => {
+        const runs = runSet.runs.filter((run) => run.scenarioId === scenario.scenarioId);
+        return runs.length > 0 ? aggregateBenchmarkRuns({ scenario, runs }) : null;
+      });
+    summaries.push({
+      runSetId: runSet.runSetId,
+      runCount: runSet.runs.length,
+      scenarioCount: aggregates.filter(Boolean).length,
+      claimsAllowed: aggregates.some((aggregate) => aggregate?.claimsAllowed === true),
+      scenarios: aggregates.filter(Boolean).map((aggregate) => ({
+        scenarioId: aggregate.scenarioId,
+        expectedProfile: aggregate.expectedProfile,
+        claimsAllowed: aggregate.claimsAllowed,
+        comparisons: aggregate.comparisons,
+        lightObjectives: aggregate.lightObjectives,
+        modeAggregates: aggregate.modeAggregates,
+        contextInflation: aggregate.contextInflation ?? null,
+      })),
+    });
+  }
+  const output = {
+    schemaVersion: 1,
+    benchmarkVersion: BENCHMARK_VERSION,
+    status: summaries.length === 0 ? "NOT_MEASURED" : "MEASURED",
+    claimsAllowed: summaries.some((summary) => summary.claimsAllowed),
+    scenarioCount: scenarios.length,
+    runSets: summaries,
+    claimPolicy: "No efficiency claim is allowed when trusted measurements are unavailable or non-comparable.",
+  };
+  if (options.json) console.log(JSON.stringify(output));
+  else {
+    console.log(`Benchmark status: ${output.status}`);
+    console.log(`Run sets: ${summaries.length}`);
+    console.log(`Claims allowed: ${output.claimsAllowed ? "yes (observational only)" : "no"}`);
+    if (summaries.length === 0) console.log("No provider or host benchmark measurements are present.");
+  }
+}
+
+main().catch((error) => {
+  console.error(`ForgeLoop benchmark summary: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/validate-execution-profile-benchmarks.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assertSchema, readSchema } from "../src/core/schema-validation.js";
+import { getPackageRoot } from "../src/core/templates.js";
+import { aggregateBenchmarkRuns, BENCHMARK_MODES } from "../src/core/execution-profile-benchmarks.js";
+import { readBenchmarkRunSets, readBenchmarkScenarios } from "./lib/execution-profile-benchmark-io.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const defaultResultsDirectory = path.join(repositoryRoot, "benchmarks", "execution-profiles", "results");
+
+function parseArgs(argv) {
+  const options = { results: defaultResultsDirectory, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--json") options.json = true;
+    else if (argument === "--results") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) throw new Error("--results requires a value");
+      options.results = value;
+    } else if (argument === "--help" || argument === "-h") options.help = true;
+    else throw new Error(`unknown option: ${argument}`);
+  }
+  return options;
+}
+
+function assertCompleteRunSet(scenario, runs) {
+  if (runs.length === 0) throw new Error(`${scenario.scenarioId}: no raw runs found`);
+  const byMode = Object.fromEntries(BENCHMARK_MODES.map((mode) => [mode, runs.filter((run) => run.mode === mode)]));
+  const counts = new Set(BENCHMARK_MODES.map((mode) => byMode[mode].length));
+  if (counts.size !== 1 || counts.has(0)) throw new Error(`${scenario.scenarioId}: every mode must have the same non-zero run count`);
+  const expectedIndexes = byMode.direct.map((run) => run.runIndex).sort((a, b) => a - b);
+  for (const mode of BENCHMARK_MODES) {
+    const indexes = byMode[mode].map((run) => run.runIndex).sort((a, b) => a - b);
+    if (JSON.stringify(indexes) !== JSON.stringify(expectedIndexes)) {
+      throw new Error(`${scenario.scenarioId}: ${mode} run indexes do not match direct baseline`);
+    }
+  }
+  return aggregateBenchmarkRuns({ scenario, runs });
+}
+
+async function validateStoredAggregates(resultsDirectory, runSetId, scenarios, expectedAggregates) {
+  const schema = await readSchema("execution-profile-benchmark-aggregate", getPackageRoot());
+  const aggregateDirectory = path.join(resultsDirectory, "aggregate", runSetId);
+  const aggregateEntries = await readdir(aggregateDirectory, { withFileTypes: true });
+  const expectedNames = new Set(scenarios.map((scenario) => `${scenario.scenarioId}.json`));
+  for (const entry of aggregateEntries) {
+    if (entry.isFile() && entry.name.endsWith(".json") && entry.name !== "summary.json" && !expectedNames.has(entry.name)) {
+      throw new Error(`${runSetId}: aggregate has an unexpected scenario file: ${entry.name}`);
+    }
+  }
+  for (const aggregate of expectedAggregates) {
+    const filename = path.join(resultsDirectory, "aggregate", runSetId, `${aggregate.scenarioId}.json`);
+    const stored = JSON.parse(await readFile(filename, "utf8"));
+    assertSchema(stored, schema, filename);
+    if (JSON.stringify(stored) !== JSON.stringify(aggregate)) {
+      throw new Error(`${aggregate.scenarioId}: stored aggregate does not reproduce raw measurements`);
+    }
+  }
+  const summaryPath = path.join(resultsDirectory, "aggregate", runSetId, "summary.json");
+  const summary = JSON.parse(await readFile(summaryPath, "utf8"));
+  if (summary.runSetId !== runSetId
+    || summary.scenarioCount !== scenarios.length
+    || summary.runCount !== expectedAggregates.reduce((sum, aggregate) => sum + aggregate.generatedFromRunCount, 0)
+    || summary.claimsAllowed !== expectedAggregates.some((aggregate) => aggregate.claimsAllowed)) {
+    throw new Error(`${runSetId}: aggregate summary identity is inconsistent`);
+  }
+}
+
+async function readAggregateRunSetNames(resultsDirectory) {
+  try {
+    return (await readdir(path.join(resultsDirectory, "aggregate"), { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log("Usage: npm run benchmark:profiles:check -- [--results <directory>] [--json]");
+    return;
+  }
+  const scenarios = await readBenchmarkScenarios(repositoryRoot);
+  const resultsDirectory = path.resolve(options.results);
+  const runSets = await readBenchmarkRunSets(resultsDirectory);
+  const aggregateRunSetNames = await readAggregateRunSetNames(resultsDirectory);
+  const rawRunSetNames = new Set(runSets.map((runSet) => runSet.runSetId));
+  for (const name of aggregateRunSetNames) {
+    if (!rawRunSetNames.has(name)) throw new Error(`${name}: aggregate exists without raw benchmark history`);
+  }
+  if (runSets.length === 0) {
+    const output = { status: "VALID", benchmarkStatus: "NOT_MEASURED", scenarioCount: scenarios.length, runSets: 0 };
+    console.log(options.json ? JSON.stringify(output) : "Benchmark schemas valid; no measured run sets are present.");
+    return;
+  }
+  const results = [];
+  for (const runSet of runSets) {
+    const aggregates = scenarios.map((scenario) => assertCompleteRunSet(
+      scenario,
+      runSet.runs.filter((run) => run.scenarioId === scenario.scenarioId),
+    ));
+    await validateStoredAggregates(resultsDirectory, runSet.runSetId, scenarios, aggregates);
+    results.push({ runSetId: runSet.runSetId, runCount: runSet.runs.length, claimsAllowed: aggregates.some((aggregate) => aggregate.claimsAllowed) });
+  }
+  const output = { status: "VALID", benchmarkStatus: "MEASURED", scenarioCount: scenarios.length, runSets: results };
+  console.log(options.json ? JSON.stringify(output) : `Benchmark schemas and aggregates valid for ${results.length} run set(s).`);
+}
+
+main().catch((error) => {
+  console.error(`ForgeLoop benchmark validation: ${error.message}`);
+  process.exitCode = 1;
+});

package/src/cli.js

@@ -35,6 +35,8 @@ import { formatActionVerifyResult } from "./commands/action-verify.js";
 import { formatActionShowResult } from "./commands/action-show.js";
 import { formatActionReconcileResult } from "./commands/action-reconcile.js";
 import { formatMetricsResult } from "./commands/metrics.js";
+import { formatUsageRecordResult } from "./commands/usage-record.js";
+import { formatEfficiencyResult } from "./commands/efficiency.js";
 import { formatEvalResult } from "./commands/eval.js";
 import { formatApprovalRequestResult } from "./commands/approval-request.js";
 import { formatApprovalResolveResult } from "./commands/approval-resolve.js";
@@ -48,14 +50,14 @@ import { formatTraceResult } from "./commands/trace.js";
 import { formatReflectResult } from "./commands/reflect.js";
 import { formatProgressResult } from "./commands/progress.js";
 import { formatRecordDecisionCriterionResult } from "./commands/record-decision-criterion.js";
-import { formatNextActionResult } from "./commands/next.js";
+import { formatNextActionResult, formatCompactNextActionResult } from "./commands/next.js";
 import { formatContinuityResult } from "./commands/continuity.js";
 import { formatRecordContinuityResult } from "./commands/record-continuity.js";
 import { formatReconcileContinuityResult } from "./commands/reconcile-continuity.js";
 import { formatClearContinuityResult } from "./commands/clear-continuity.js";
 import { formatTaskCreateResult } from "./commands/task-create.js";
 import { formatTaskListResult } from "./commands/task-list.js";
-import { formatTaskShowResult } from "./commands/task-show.js";
+import { formatTaskShowResult, formatCompactTaskShowResult } from "./commands/task-show.js";
 import { formatTaskScopeResult } from "./commands/task-scope.js";
 import { formatTaskMigrateResult } from "./commands/task-migrate.js";
 import { formatMigrateProtocolResult } from "./commands/migrate-protocol.js";
@@ -384,7 +386,8 @@ export const COMMAND_HANDLERS = Object.freeze({
   },
   next: async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS.next({ target, packageRoot, options });
-    renderJsonOr(options, result, formatNextActionResult);
+    if (options.compact) console.log(formatCompactNextActionResult(result));
+    else renderJsonOr(options, result, formatNextActionResult);
     return 0;
   },
   continuity: async ({ target, packageRoot, options }) => {
@@ -510,6 +513,14 @@ export const COMMAND_HANDLERS = Object.freeze({
     const { result } = await COMMAND_EXECUTORS.metrics({ target, packageRoot, options });
     renderJsonOr(options, result, formatMetricsResult); return 0;
   },
+  "usage-record": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["usage-record"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatUsageRecordResult); return 0;
+  },
+  efficiency: async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS.efficiency({ target, packageRoot, options });
+    renderJsonOr(options, result, formatEfficiencyResult); return 0;
+  },
   eval: async ({ target, packageRoot, options }) => {
     const { result, exitCode } = await COMMAND_EXECUTORS.eval({ target, packageRoot, options });
     renderJsonOr(options, result, formatEvalResult); return exitCode;
@@ -677,7 +688,8 @@ export const COMMAND_HANDLERS = Object.freeze({
   },
   "task-show": async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS["task-show"]({ target, packageRoot, options });
-    renderJsonOr(options, result, formatTaskShowResult);
+    if (options.compact) console.log(formatCompactTaskShowResult(result));
+    else renderJsonOr(options, result, formatTaskShowResult);
     return 0;
   },
   "task-lock-status": async ({ target, packageRoot, options }) => {

package/src/commands/efficiency.js

@@ -0,0 +1,12 @@
+import { buildEfficiencyReport } from "../core/efficiency.js";
+import { withResolvedTask } from "../core/task-command.js";
+
+export async function runEfficiency({ target, packageRoot, taskId, baselinePath = null, runtimeContext = null }) {
+  return withResolvedTask(target, { taskId, packageRoot, explicitRequired: true }, (ctx) =>
+    buildEfficiencyReport({ target, packageRoot, taskId: ctx.taskId, baselinePath, runtimeContext }));
+}
+
+export function formatEfficiencyResult(result) {
+  return `${JSON.stringify(result, null, 2)}\n`;
+}
+

package/src/commands/eval.js

@@ -1,6 +1,12 @@
 import { evaluateTrajectory } from "../core/trajectory-evaluation.js";
 import { withResolvedTask } from "../core/task-command.js";
-export async function runEval({ target, packageRoot, taskId, scenarioPath }) {
-  return withResolvedTask(target, { taskId, packageRoot }, (ctx) => evaluateTrajectory({ target, packageRoot, taskId: ctx.taskId, scenarioPath }));
+export async function runEval({ target, packageRoot, taskId, scenarioPath, runtimeContext = null }) {
+  return withResolvedTask(target, { taskId, packageRoot }, (ctx) => evaluateTrajectory({
+    target,
+    packageRoot,
+    taskId: ctx.taskId,
+    scenarioPath,
+    runtimeContext,
+  }));
 }
 export function formatEvalResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }

package/src/commands/metrics.js

@@ -1,7 +1,7 @@
 import { buildTrajectoryMetrics } from "../core/trajectory-metrics.js";
 import { withResolvedTask } from "../core/task-command.js";
-export async function runMetrics({ target, packageRoot, taskId }) {
+export async function runMetrics({ target, packageRoot, taskId, runtimeContext = null }) {
   return withResolvedTask(target, { taskId, packageRoot }, (ctx) =>
-    buildTrajectoryMetrics({ target, packageRoot, taskId: ctx.taskId }));
+    buildTrajectoryMetrics({ target, packageRoot, taskId: ctx.taskId, runtimeContext }));
 }
 export function formatMetricsResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }

package/src/commands/next.js

@@ -1,15 +1,35 @@
 import { getNextAction } from "../core/next-action.js";
 import { withResolvedTask } from "../core/task-command.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { projectExecutionProfile } from "../core/execution-profile.js";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext }) {
+export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
-    return getNextAction({
+    const result = await getNextAction({
       target,
       packageRoot,
       taskId: ctx?.taskId ?? null,
       authorityContext,
       runtimeContext,
     });
+    if (!compact) return result;
+    const compactTaskId = ctx?.taskId ?? (result.taskId && result.taskId !== "unknown" ? result.taskId : null);
+    let profile = null;
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId: compactTaskId });
+      profile = projectExecutionProfile(route.value);
+    } catch {
+      // Legacy and incomplete tasks remain readable without a profile.
+    }
+    return {
+      taskId: compactTaskId ?? result.taskId,
+      phase: result.currentPhase,
+      profile,
+      nextAction: result.nextAction,
+      command: result.commandSpecs?.[0]?.argv ?? [],
+      terminal: result.terminal,
+      errors: result.reasonCodes ?? result.reasons?.map((reason) => reason.code) ?? [],
+    };
   });
 }
 
@@ -50,3 +70,7 @@ export function formatNextActionResult(result) {
   if (result.terminal) lines.push("STATE: TERMINAL");
   return `${lines.join("\n")}\n`;
 }
+
+export function formatCompactNextActionResult(result) {
+  return `${JSON.stringify(result)}\n`;
+}

package/src/commands/route.js

@@ -1,11 +1,24 @@
 import { evaluateRoute } from "../core/router.js";
 import { persistRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
+import { readConfig } from "../core/config.js";
 import { withTaskMutation } from "../core/task-command.js";
 
-export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, taskId, task }) {
+export async function runRoute({ target, packageRoot, workType, surfaces, risks, platforms, behaviorChange, executableChange, executionProfile = null, taskId, task }) {
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "route", async (ctx) => {
     const effectiveTaskId = ctx?.taskId ?? null;
+    let contract = null;
+    try {
+      contract = (await readContract(target, packageRoot, { taskId: effectiveTaskId })).value;
+    } catch (error) {
+      if (error.code !== "ARTIFACT_MISSING") throw error;
+    }
+    let configuredProfile = "auto";
+    try {
+      configuredProfile = (await readConfig(target, packageRoot)).executionProfile ?? "auto";
+    } catch (error) {
+      if (error.code !== "ARTIFACT_MISSING") throw error;
+    }
     const route = evaluateRoute({
       workType,
       surfaces,
@@ -13,6 +26,11 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
       platforms,
       behaviorChange,
       executableChange,
+    }, {
+      contract,
+      taskDescriptor: ctx?.descriptor ?? null,
+      configuredProfile,
+      requestedProfile: executionProfile,
     });
     if (target && packageRoot) {
       let contractFingerprint;
@@ -28,7 +46,7 @@ export async function runRoute({ target, packageRoot, workType, surfaces, risks,
 }
 
 export function formatRouteResult(result) {
-  const lines = ["Selected:"];
+  const lines = [`Execution profile: ${result.executionProfile?.resolved ?? "legacy"}`, "Selected:"];
   if (result.guides.length === 0) {
     lines.push("- none (use the relevant domain guide for this documentation task)");
   } else {

package/src/commands/task-show.js

@@ -7,6 +7,8 @@ import { readContract } from "../core/contract.js";
 import { fileExists, ensureWithin } from "../core/filesystem.js";
 import { E_TASK_NOT_FOUND } from "../core/error-codes.js";
 import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { projectExecutionProfile } from "../core/execution-profile.js";
 
 function taskError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -15,7 +17,7 @@ function taskError(code, message, artifacts = []) {
   return error;
 }
 
-export async function runTaskShow({ target, packageRoot, taskId } = {}) {
+export async function runTaskShow({ target, packageRoot, taskId, compact = false } = {}) {
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true, selectionMode: TASK_SELECTION_MODES.READ });
   const effectiveTaskId = context.taskId;
 
@@ -56,7 +58,7 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     };
   }
 
-  return {
+  const result = {
     taskId: effectiveTaskId,
     taskKey: context.taskKey,
     directory: taskDirectory(effectiveTaskId),
@@ -69,6 +71,29 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     createdAt: descriptor.createdAt,
     updatedAt: descriptor.updatedAt,
   };
+  if (!compact) return result;
+  let profile = null;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId: effectiveTaskId });
+    profile = projectExecutionProfile(route.value);
+  } catch {
+    // Legacy routes remain readable without adaptive profile metadata.
+  }
+  return {
+    taskId: result.taskId,
+    phase: result.phase,
+    profile,
+    claimState: result.claimState,
+    mutationAllowed: result.mutationAllowed,
+    recoveryStatus: result.recoveryStatus,
+    lock: result.lock?.classification?.status ?? null,
+    artifacts: Object.fromEntries(Object.entries(result.artifacts).map(([name, artifact]) => [name, artifact.exists])),
+    errors: [...new Set([
+      ...(result.reasonCodes ?? []),
+      ...(result.errors ?? []).flatMap((error) => [error.code, error.causeCode]).filter(Boolean),
+      ...(result.ownershipErrors ?? []).flatMap((error) => [error.code, error.causeCode]).filter(Boolean),
+    ])],
+  };
 }
 
 export function formatTaskShowResult(result) {
@@ -93,3 +118,7 @@ export function formatTaskShowResult(result) {
   ];
   return `${lines.join("\n")}\n`;
 }
+
+export function formatCompactTaskShowResult(result) {
+  return `${JSON.stringify(result)}\n`;
+}

package/src/commands/usage-record.js

@@ -0,0 +1,61 @@
+import { readWorkState } from "../core/work-state.js";
+import { normalizeUsage, writeTaskUsage } from "../core/usage.js";
+import { appendProtocolEvent } from "../core/events.js";
+import { withTaskMutation } from "../core/task-command.js";
+
+export async function runUsageRecord({
+  target,
+  packageRoot,
+  taskId,
+  provider = null,
+  model = null,
+  inputTokens = null,
+  outputTokens = null,
+  cacheReadTokens = null,
+  cacheWriteTokens = null,
+  totalTokens = null,
+  costUsd = null,
+  source = "ACTOR_REPORTED",
+} = {}) {
+  if (source !== "ACTOR_REPORTED") {
+    const error = new Error("usage-record accepts only ACTOR_REPORTED; provider and host reports must cross the trusted integration boundary");
+    error.code = "E_USAGE_SOURCE_INVALID";
+    throw error;
+  }
+  return withTaskMutation(target, { taskId, packageRoot }, "usage-record", async (ctx) => {
+    const effectiveTaskId = ctx.taskId;
+    const usage = normalizeUsage({
+      provider,
+      model,
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      totalTokens,
+      costUsd,
+      source,
+    }, { allowedSources: ["ACTOR_REPORTED"] });
+    const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
+    const artifact = await writeTaskUsage(target, packageRoot, {
+      taskId: effectiveTaskId,
+      usage,
+      recordedAt: new Date().toISOString(),
+    });
+    await appendProtocolEvent(target, {
+      taskId: effectiveTaskId,
+      event: "USAGE_RECORDED",
+      details: {
+        source: usage.source,
+        fields: Object.keys(usage).filter((key) => usage[key] !== null && key !== "source").sort(),
+        verificationCycle: state?.verificationCycle ?? null,
+        usageArtifact: artifact.path,
+      },
+    }, packageRoot, { taskId: effectiveTaskId });
+    return { taskId: effectiveTaskId, path: artifact.path, usage: artifact.value.usage, recordedAt: artifact.value.recordedAt };
+  });
+}
+
+export function formatUsageRecordResult(result) {
+  return `Usage recorded: ${result.path}\nSource: ${result.usage.source}\nTotal tokens: ${result.usage.totalTokens ?? "unknown"}\n`;
+}
+

package/src/core/artifact-registry.js

@@ -283,6 +283,18 @@ export const ARTIFACT_REGISTRY = Object.freeze({
     isPersisted: true,
     description: "Immutable trajectory evaluation results compiled from the canonical trace against a local reference scenario.",
   }),
+  usage: Object.freeze({
+    key: "usage",
+    scope: "TASK",
+    path: `${TASK_STATE_ROOT}/<task-key>/${TASK_ARTIFACT_FILES.usage}`,
+    schema: "usage",
+    owner: "ACTOR_OR_TRUSTED_HOST",
+    mutability: "OVERWRITTEN_ON_USAGE_RECORD",
+    trustRole: "INFORMATIONAL_USAGE_TELEMETRY",
+    isPublic: true,
+    isPersisted: true,
+    description: "Task-scoped token, cost, model, and provider telemetry; never verification or completion evidence.",
+  }),
   workspaceBinding: Object.freeze({
     key: "workspaceBinding",
     scope: "TASK",

package/src/core/cli-command-definitions.js

@@ -139,6 +139,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
       "--platform": Object.freeze({ targetKey: "platforms", parseType: "string", takesValue: true, valueName: "value", repeatable: true, missingValueMessage: "--platform requires a value", description: "affected platform" }),
       "--behavior-change": Object.freeze({ targetKey: "behaviorChange", parseType: "boolean", takesValue: false, description: "declare behavior change" }),
       "--executable-change": Object.freeze({ targetKey: "executableChange", parseType: "boolean", takesValue: false, description: "declare executable/configuration change" }),
+      "--execution-profile": Object.freeze({ targetKey: "executionProfile", parseType: "string", takesValue: true, valueName: "profile", missingValueMessage: "--execution-profile requires auto, light, balanced, or full", description: "requested execution profile; safety floors always win" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit route result as JSON" }),
     }),
     writes: [".forgeloop/task-state/<taskKey>/routing-result.json"],
@@ -183,6 +184,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "emit a bounded next-action projection" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],
@@ -381,6 +383,30 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     }), writes: [], removes: [], mayExecuteExternalProcess: false,
     description: "Projects trajectory, action, execution, timing, and known usage metrics without mutating state.",
   }),
+  "usage-record": Object.freeze({
+    name: "usage-record", category: "diagnostics", mutation: "MUTATING",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--provider": Object.freeze({ targetKey: "usageProvider", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--provider requires a name", description: "provider name reported by the actor" }),
+      "--model": Object.freeze({ targetKey: "usageModel", parseType: "string", takesValue: true, valueName: "name", missingValueMessage: "--model requires a name", description: "model name reported by the actor" }),
+      "--input-tokens": Object.freeze({ targetKey: "usageInputTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--input-tokens requires a non-negative integer", description: "provider-reported input token count" }),
+      "--output-tokens": Object.freeze({ targetKey: "usageOutputTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--output-tokens requires a non-negative integer", description: "provider-reported output token count" }),
+      "--cache-read-tokens": Object.freeze({ targetKey: "usageCacheReadTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--cache-read-tokens requires a non-negative integer", description: "provider-reported cache-read token count" }),
+      "--cache-write-tokens": Object.freeze({ targetKey: "usageCacheWriteTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--cache-write-tokens requires a non-negative integer", description: "provider-reported cache-write token count" }),
+      "--total-tokens": Object.freeze({ targetKey: "usageTotalTokens", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--total-tokens requires a non-negative integer", description: "provider-reported total token count; never estimated" }),
+      "--cost-usd": Object.freeze({ targetKey: "usageCostUsd", parseType: "string", takesValue: true, valueName: "amount", missingValueMessage: "--cost-usd requires a non-negative amount", description: "provider-reported cost in USD; never estimated" }),
+      "--source": Object.freeze({ targetKey: "usageSource", parseType: "string", takesValue: true, valueName: "kind", missingValueMessage: "--source requires ACTOR_REPORTED", description: "usage source; CLI fallback accepts only ACTOR_REPORTED" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit usage telemetry as JSON" }),
+    }), writes: [".forgeloop/task-state/<taskKey>/usage.json", ".forgeloop/task-state/<taskKey>/events.ndjson"], removes: [], mayExecuteExternalProcess: false,
+    description: "Records actor-reported usage telemetry without treating it as verification evidence.",
+  }),
+  efficiency: Object.freeze({
+    name: "efficiency", category: "diagnostics", mutation: "READ_ONLY",
+    options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
+      "--baseline": Object.freeze({ targetKey: "baselinePath", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--baseline requires a project-local path", description: "optional comparable efficiency baseline JSON" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit efficiency metrics as JSON" }),
+    }), writes: [], removes: [], mayExecuteExternalProcess: false,
+    description: "Projects usage and timing efficiency, comparing only against a metadata-compatible local baseline.",
+  }),
   eval: Object.freeze({
     name: "eval", category: "diagnostics", mutation: "MUTATING",
     options: Object.freeze({ ...CLI_COMMON_OPTIONS, ...CLI_TASK_OPTION,
@@ -900,6 +926,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze({
       ...CLI_COMMON_OPTIONS,
       ...CLI_TASK_OPTION,
+      "--compact": Object.freeze({ targetKey: "compact", parseType: "boolean", takesValue: false, description: "emit a bounded task-status projection" }),
       "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit structured output as JSON" }),
     }),
     writes: [],