@cassiomc1/forgeloop 1.6.4 → 1.7.0

package/docs/GETTING_STARTED.md

@@ -26,6 +26,34 @@ Core mental model:
 - `checks = verification truth`
 - `receipt = completion/publication record`
 
+### Adaptive execution profiles
+
+ForgeLoop uses `executionProfile` to choose the appropriate process and context
+depth without changing its assurance guarantees. It is separate from
+`complianceMode`, which controls policy enforcement.
+
+```text
+auto → light | balanced | full
+```
+
+Small, local, reversible documentation and UI work normally resolves to
+`light`; behavior changes and ordinary application work resolve to
+`balanced`; authentication, publication, infrastructure, secrets, personal
+data, critical paths, and irreversible work resolve to `full`. A CLI or project
+request may raise the profile, but never lower the deterministic safety floor.
+
+For compact host context, use:
+
+```bash
+forgeloop next --task task-contact-form-001 --compact --json
+forgeloop task-show --task task-contact-form-001 --compact --json
+```
+
+These commands do not bypass contracts, gates, verification, provenance,
+lifecycle phases, or validator-backed completion. Usage telemetry is optional,
+never estimated, and never verification evidence; `efficiency --task` compares
+only against a metadata-compatible local baseline.
+
 ---
 
 ## 2. Prerequisites

package/docs/MCP.md

@@ -50,6 +50,7 @@ Capability flags (process-scoped, immutable after launch):
 - `forgeloop://task/{taskId}/action/{actionId}`
 - `forgeloop://task/{taskId}/approvals`
 - `forgeloop://task/{taskId}/metrics`
+- `forgeloop://task/{taskId}/context` — bounded profile-aware host context
 - `forgeloop://task/{taskId}/evaluations`
 - `forgeloop://project/capability-policy`
 
@@ -83,6 +84,11 @@ content.
 Raw recovery artifacts, transaction journals, lock files, and unbounded event
 ledgers are intentionally not exposed.
 
+The context resource is read-only. It lets an MCP host adapt presentation depth
+from the canonical resolved execution profile while preserving lifecycle
+phases, required gates, verification truth, authority, provenance, and
+validator-backed completion.
+
 Optional workspace binding, handoff, responsibility, verification-scope,
 RevisionProvider, SigningProvider, and attestation operations remain governed
 by the same canonical command executors when exposed by a compatible host.

package/docs/RELEASE_CHECKLIST.md

@@ -16,6 +16,10 @@ preparation and verification checklist; it does not authorize publication.
 - [ ] `npm run dependency:policy` passes without adding runtime dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.
+- [ ] `npm run benchmark:profiles:check` passes; absent provider/host history
+      is reported as `NOT_MEASURED`, never as zero or a passing efficiency claim.
+- [ ] `npm run benchmark:profiles:regression` reports the observed status;
+      `EFFICIENCY_REGRESSION` remains a non-blocking warning.
 - [ ] `npm run coverage` passes the configured global and critical-module gates.
 - [ ] `npm run docs:check`, `npm run docs:generated:check`,
       `npm run docs:conformance`, and `npm run docs:examples:check` pass.

package/docs/TROUBLESHOOTING.md

@@ -986,6 +986,7 @@ forgeloop next --task <id> --json
 | `E_DIAGNOSTIC_CASE_CYCLE_MISMATCH` | Diagnostic case verification cycle does not match the active work state verification cycle. | Record the diagnostic case for the current active verification cycle. |
 | `E_DIAGNOSTIC_CASE_EVIDENCE_INVALID` | A diagnostic case evidence reference does not match any check from the active verification cycle. | Reference check IDs recorded during the active verification cycle. |
 | `E_DIAGNOSTIC_CASE_INVALID` | Structured diagnostic case details or parameters are malformed. | Provide valid observations, contributors, hypotheses with settlement criteria, and nextSafeAction. |
+| `E_EFFICIENCY_BASELINE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_EVIDENCE_COVERAGE_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_EVIDENCE_COVERAGE_PARTIAL` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_EVIDENCE_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -993,6 +994,9 @@ forgeloop next --task <id> --json
 | `E_EVIDENCE_PARTIAL` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_EVIDENCE_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_EVIDENCE_STALE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_EXECUTION_PROFILE_INCONSISTENT` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_EXECUTION_PROFILE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_EXECUTION_PROFILE_SAFETY_FLOOR_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_EXECUTION_REF_INVALID` | Referenced execution ID does not exist. | Re-run check via forgeloop run-check. |
 | `E_FAILURE_SIGNATURE_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_FUTURE_LIFECYCLE_EVIDENCE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1123,6 +1127,8 @@ forgeloop next --task <id> --json
 | `E_TRACE_SNAPSHOT_INCONSISTENT` | Task artifacts changed while the execution trace was being read. | Rerun the read-only projection to obtain a consistent view. |
 | `E_TRAJECTORY_REFERENCE_REQUIRED` | Comparative efficiency requires a reference scenario with positive comparableSteps. | Provide --scenario with reference.comparableSteps, or omit efficiency from the result. |
 | `E_TRAJECTORY_SCENARIO_INVALID` | Trajectory scenario file is missing required fields or schema-invalid. | Correct the scenario JSON against schemas/trajectory-scenario.schema.json. |
+| `E_USAGE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_USAGE_SOURCE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_VERIFICATION_EXECUTION_INVALID` | The trusted verification execution adapter returned incomplete or invalid execution metadata. | Repair the adapter contract and rerun verification; do not promote incomplete execution evidence. |
 | `E_VERIFICATION_ISOLATION_UNAVAILABLE` | Verification cannot run because the required disposable or system isolation boundary is unavailable. | Use a trusted ForgeLoop execution adapter with the required isolation mode; never run the check in the live project. |
 | `E_VERIFICATION_SCOPE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |

package/docs/UNIVERSAL_INTEGRATION.md

@@ -35,6 +35,64 @@ import {
   FORCE_DESTRUCTIVE) describe what an invocation would do; launch policy
   decides what is allowed.
 
+### Profile-aware context
+
+The resolved execution profile is available from the persisted route and from
+compact `next`/`task-show` projections. `complianceMode` remains the policy
+enforcement dimension; `executionProfile` is the independent process/context
+depth dimension.
+
+The API's read-only `task/context` resource provides the canonical host
+projection for this decision. It includes the objective, deliverables,
+constraints, selected guide IDs, current phase, next action, verification
+requirements, resolved profile, and bounded optional-context policy. The MCP
+adapter exposes the same projection at
+`forgeloop://task/{taskId}/context`.
+
+For `light`, an adapter should send only the current objective, deliverables,
+hard constraints, resolved profile, selected guide IDs or relevant guide
+sections, current phase, exact next action, and verification requirements. It
+should reuse unchanged state locally instead of repeatedly sending full
+ledgers, schemas, receipts, or protocol documents. This is presentation
+optimization only: required gates, verification truth, authority, provenance,
+and validated completion remain unchanged. A lifecycle fast path is not part
+of protocol v1.
+
+Optional reflection, trajectory evaluation, handoff, responsibility,
+attestation, benchmark, and continuity artifacts are lazy and should be
+created only when policy, an explicit request, or recovery requires them.
+
+The profile never authorizes a lifecycle-phase or required-gate skip. A phase
+may be absent only when the canonical protocol marks it not applicable;
+presentation depth cannot change evidence, verification truth, authority,
+provenance, safety-floor, or validator-backed completion requirements.
+
+### Usage and efficiency boundary
+
+Create a context with an optional trusted provider:
+
+```js
+const context = createForgeLoopContext({
+  usageProvider: {
+    async getTaskUsage({ projectPath, taskId }) {
+      return hostUsageStore.lookup({ projectPath, taskId });
+    },
+  },
+});
+```
+
+The provider returns `PROVIDER_REPORTED` or `HOST_REPORTED` snapshots. The CLI
+fallback is explicitly `ACTOR_REPORTED`; missing fields remain `null` and no
+token or cost estimate is produced. Usage never satisfies a check or
+completion requirement. Use `efficiency --task --baseline <project-local-json>`
+only for metadata-compatible comparisons; otherwise the result is
+`NOT_COMPARABLE`.
+
+For measured execution-profile comparisons, use the reproducible benchmark
+commands in [`EXECUTION_PROFILE_BENCHMARKS.md`](./EXECUTION_PROFILE_BENCHMARKS.md).
+The benchmark source policy accepts provider or host observations only and
+keeps unavailable or non-comparable measurements out of efficiency claims.
+
 ## Consumers
 
 | Surface | Entry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -22,12 +22,14 @@
     "src",
     "ENG",
     "schemas",
+    "benchmarks/execution-profiles",
     ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
     "GUIDE_ROUTER.md",
     "LOOP_ENGINEERING.md",
     "PROTOCOL_INTEGRATION.md",
+    "AGENT_COMPATIBILITY.md",
     "LOOP_SYSTEM_DESIGN.md",
     "QUALITY_SCORECARD.md",
     "TERMINOLOGY.md",
@@ -64,8 +66,14 @@
     "docs/SIGNING_PROVIDERS.md",
     "docs/PLATFORM_ADAPTERS.md",
     "docs/AGENT_PROTOCOL_SUMMARY.md",
+    "docs/EXECUTION_PROFILE_BENCHMARKS.md",
     "scripts/generate-shell-completions.mjs",
     "scripts/generate-agent-protocol-summary.mjs",
+    "scripts/run-execution-profile-benchmarks.mjs",
+    "scripts/summarize-execution-profile-benchmarks.mjs",
+    "scripts/validate-execution-profile-benchmarks.mjs",
+    "scripts/check-efficiency-regression.mjs",
+    "scripts/lib/execution-profile-benchmark-io.mjs",
     "scripts/benchmark-cli-startup.mjs",
     "scripts/check-critical-coverage.mjs",
     "scripts/check-changelog-freshness.mjs",
@@ -103,7 +111,11 @@
     "mcp:setup": "node scripts/mcp-setup.mjs",
     "mcp:pack:check": "node scripts/mcp-package-smoke.mjs",
     "poc:evidence:verify": "node scripts/verify_poc_evidence.mjs",
-    "poc:evidence:test": "node --test poc/test/poc-evidence-publication.test.js"
+    "poc:evidence:test": "node --test poc/test/poc-evidence-publication.test.js",
+    "benchmark:profiles": "node scripts/run-execution-profile-benchmarks.mjs",
+    "benchmark:profiles:summary": "node scripts/summarize-execution-profile-benchmarks.mjs",
+    "benchmark:profiles:check": "node scripts/validate-execution-profile-benchmarks.mjs",
+    "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs"
   },
   "devDependencies": {
     "c8": "^12.0.0",

package/schemas/config.schema.json

@@ -8,6 +8,7 @@
     "schemaVersion": { "const": 1 },
     "protocolVersion": { "const": 1 },
     "complianceMode": { "enum": ["advisory", "standard", "strict"] },
+    "executionProfile": { "enum": ["auto", "light", "balanced", "full"] },
     "policy": { "type": "string", "minLength": 1 },
     "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "requiredEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },

package/schemas/execution-profile-benchmark-aggregate.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/execution-profile-benchmark-aggregate.schema.json",
+  "title": "ForgeLoop execution-profile benchmark aggregate",
+  "type": "object",
+  "required": ["schemaVersion", "benchmarkVersion", "runSetId", "scenarioId", "expectedProfile", "modeAggregates", "comparisons", "lightObjectives", "sourcePolicy", "claimsAllowed", "generatedFromRunCount"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "benchmarkVersion": { "const": "1" },
+    "runSetId": { "type": "string", "minLength": 1 },
+    "scenarioId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" },
+    "expectedProfile": { "enum": ["light", "balanced", "full"] },
+    "modeAggregates": {
+      "type": "object",
+      "required": ["direct", "forgeloopBalanced", "forgeloopAdaptive"],
+      "additionalProperties": { "type": "object" }
+    },
+    "comparisons": {
+      "type": "object",
+      "required": ["direct", "forgeloopBalanced", "forgeloopAdaptive"],
+      "additionalProperties": true
+    },
+    "lightObjectives": { "type": ["object", "null"] },
+    "contextInflation": {
+      "type": "object",
+      "required": ["status", "comparablePairs", "inflatedPairs", "lightContextTokens", "balancedContextTokens", "blocking", "reason"],
+      "properties": {
+        "status": { "enum": ["CONTEXT_INFLATION", "NOT_DETECTED", "NOT_COMPARABLE"] },
+        "comparablePairs": { "type": "integer", "minimum": 0 },
+        "inflatedPairs": { "type": "integer", "minimum": 0 },
+        "lightContextTokens": { "type": "object" },
+        "balancedContextTokens": { "type": "object" },
+        "blocking": { "const": false },
+        "reason": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "sourcePolicy": { "const": "PROVIDER_REPORTED_OR_HOST_REPORTED_ONLY" },
+    "claimsAllowed": { "type": "boolean" },
+    "generatedFromRunCount": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/schemas/execution-profile-benchmark-run.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/execution-profile-benchmark-run.schema.json",
+  "title": "ForgeLoop execution-profile benchmark run",
+  "type": "object",
+  "required": ["schemaVersion", "benchmarkVersion", "runSetId", "runId", "scenarioId", "mode", "runIndex", "recordedAt", "usage", "wallClockMs", "verification", "verificationCycles", "comparableSteps", "metadata"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "benchmarkVersion": { "const": "1" },
+    "runSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$" },
+    "runId": { "type": "string", "pattern": "^run-[A-Za-z0-9][A-Za-z0-9_-]{0,127}$" },
+    "scenarioId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" },
+    "mode": { "enum": ["direct", "forgeloopBalanced", "forgeloopAdaptive"] },
+    "runIndex": { "type": "integer", "minimum": 1 },
+    "recordedAt": { "type": "string", "minLength": 1 },
+    "usage": {
+      "type": "object",
+      "required": ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "costUsd", "model", "provider", "source"],
+      "properties": {
+        "inputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "outputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheReadTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheWriteTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "totalTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "costUsd": { "type": ["number", "null"], "minimum": 0 },
+        "model": { "type": ["string", "null"] },
+        "provider": { "type": ["string", "null"] },
+        "source": { "enum": ["PROVIDER_REPORTED", "HOST_REPORTED", "UNKNOWN"] }
+      },
+      "additionalProperties": false
+    },
+    "wallClockMs": { "type": ["number", "null"], "minimum": 0 },
+    "verification": { "enum": ["PASS", "FAIL", "NOT_AVAILABLE"] },
+    "verificationCycles": { "type": ["integer", "null"], "minimum": 0 },
+    "comparableSteps": { "type": ["integer", "null"], "minimum": 0 },
+    "contextUsage": { "$ref": "#/$defs/contextUsage" },
+    "quality": { "$ref": "#/$defs/quality" },
+    "metadata": {
+      "type": "object",
+      "required": ["scenarioId", "mode", "model", "provider", "promptSpecFingerprint", "projectRevision", "benchmarkVersion", "environmentClass", "requestedProfile", "resolvedProfile", "verificationCycles", "comparableSteps"],
+      "properties": {
+        "scenarioId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" },
+        "mode": { "enum": ["direct", "forgeloopBalanced", "forgeloopAdaptive"] },
+        "model": { "type": ["string", "null"] },
+        "provider": { "type": ["string", "null"] },
+        "promptSpecFingerprint": { "type": "string", "minLength": 1 },
+        "projectRevision": { "type": ["string", "null"] },
+        "benchmarkVersion": { "const": "1" },
+        "environmentClass": { "type": "string", "minLength": 1 },
+        "requestedProfile": { "type": ["string", "null"] },
+        "resolvedProfile": { "type": ["string", "null"] },
+        "verificationCycles": { "type": ["integer", "null"], "minimum": 0 },
+        "comparableSteps": { "type": ["integer", "null"], "minimum": 0 },
+        "nodeVersion": { "type": "string", "minLength": 1 },
+        "os": { "type": "string", "minLength": 1 },
+        "arch": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "contextUsage": {
+      "type": "object",
+      "required": ["source", "profile", "items"],
+      "properties": {
+        "source": { "enum": ["HOST_REPORTED", "UNKNOWN"] },
+        "profile": { "enum": ["light", "balanced", "full", null] },
+        "items": {
+          "type": "object",
+          "required": ["taskContext", "guides", "history", "protocolInstructions", "repositoryContext", "other"],
+          "properties": {
+            "taskContext": { "type": ["integer", "null"], "minimum": 0 },
+            "guides": { "type": ["integer", "null"], "minimum": 0 },
+            "history": { "type": ["integer", "null"], "minimum": 0 },
+            "protocolInstructions": { "type": ["integer", "null"], "minimum": 0 },
+            "repositoryContext": { "type": ["integer", "null"], "minimum": 0 },
+            "other": { "type": ["integer", "null"], "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "quality": {
+      "type": "object",
+      "required": ["source", "scores"],
+      "properties": {
+        "source": { "enum": ["EXTERNAL_REPORTED", "HOST_REPORTED", "UNKNOWN"] },
+        "scores": {
+          "type": "object",
+          "required": ["visualQuality", "responsiveQuality", "accessibility", "interactionPolish", "requirementsCompleteness"],
+          "properties": {
+            "visualQuality": { "type": ["number", "null"], "minimum": 0, "maximum": 5 },
+            "responsiveQuality": { "type": ["number", "null"], "minimum": 0, "maximum": 5 },
+            "accessibility": { "type": ["number", "null"], "minimum": 0, "maximum": 5 },
+            "interactionPolish": { "type": ["number", "null"], "minimum": 0, "maximum": 5 },
+            "requirementsCompleteness": { "type": ["number", "null"], "minimum": 0, "maximum": 5 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/execution-profile-benchmark-scenario.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/execution-profile-benchmark-scenario.schema.json",
+  "title": "ForgeLoop execution-profile benchmark scenario",
+  "type": "object",
+  "required": ["schemaVersion", "benchmarkVersion", "scenarioId", "description", "input", "expectedProfile", "measurements"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "benchmarkVersion": { "type": "string", "minLength": 1 },
+    "scenarioId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,127}$" },
+    "description": { "type": "string", "minLength": 1 },
+    "input": {
+      "type": "object",
+      "required": ["workType", "surfaces", "risks", "platforms"],
+      "properties": {
+        "workType": { "type": "string", "minLength": 1 },
+        "surfaces": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "risks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "platforms": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "behaviorChange": { "type": "boolean" },
+        "executableChange": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "expectedProfile": { "enum": ["light", "balanced", "full"] },
+    "referenceTask": { "$ref": "#/$defs/referenceTask" },
+    "measurements": {
+      "type": "object",
+      "required": ["direct", "forgeloopBalanced", "forgeloopAdaptive"],
+      "properties": {
+        "direct": { "$ref": "#/$defs/measurement" },
+        "forgeloopBalanced": { "$ref": "#/$defs/measurement" },
+        "forgeloopAdaptive": { "$ref": "#/$defs/measurement" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "referenceTask": {
+      "type": "object",
+      "required": ["name", "requirements", "exclusions", "artifactMode"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "requirements": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+        "exclusions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+        "artifactMode": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "measurement": {
+      "type": "object",
+      "required": ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "wallClockMs", "verification"],
+      "properties": {
+        "inputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "outputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheReadTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheWriteTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "totalTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "wallClockMs": { "type": ["number", "null"], "minimum": 0 },
+        "verification": { "enum": ["PASS", "FAIL", "NOT_AVAILABLE"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/routing-result.schema.json

@@ -8,6 +8,18 @@
     "schemaVersion": { "const": 1 },
     "protocolVersion": { "const": 1 },
     "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "executionProfile": {
+      "type": "object",
+      "required": ["requested", "floor", "resolved", "reasons", "escalated"],
+      "additionalProperties": false,
+      "properties": {
+        "requested": { "enum": ["auto", "light", "balanced", "full"] },
+        "floor": { "enum": ["light", "balanced", "full"] },
+        "resolved": { "enum": ["light", "balanced", "full"] },
+        "reasons": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "escalated": { "type": "boolean" }
+      }
+    },
     "input": { "type": "object" },
     "primary": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
     "guides": { "type": "array", "items": { "type": "string" } },

package/schemas/usage.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/usage.schema.json",
+  "title": "ForgeLoop task usage telemetry",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "recordedAt", "usage"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "recordedAt": { "type": "string", "minLength": 1 },
+    "usage": {
+      "type": "object",
+      "required": ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "costUsd", "model", "provider", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "inputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "outputTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheReadTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "cacheWriteTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "totalTokens": { "type": ["integer", "null"], "minimum": 0 },
+        "costUsd": { "type": ["number", "null"], "minimum": 0 },
+        "model": { "type": ["string", "null"] },
+        "provider": { "type": ["string", "null"] },
+        "source": { "enum": ["PROVIDER_REPORTED", "HOST_REPORTED", "ACTOR_REPORTED", "UNKNOWN"] }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/scripts/check-efficiency-regression.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { aggregateBenchmarkRuns } 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 statusForAggregate(aggregate, runs) {
+  const hasMeasuredUsage = runs.some((run) => (
+    ["PROVIDER_REPORTED", "HOST_REPORTED"].includes(run.usage.source)
+    && run.usage.totalTokens !== null
+  ));
+  if (!hasMeasuredUsage) return "NOT_MEASURED";
+  if (!aggregate.claimsAllowed) return "NOT_COMPARABLE";
+  if (aggregate.lightObjectives
+    && (aggregate.lightObjectives.p50Pass === false || aggregate.lightObjectives.p95Pass === false)) {
+    return "EFFICIENCY_REGRESSION";
+  }
+  return "OK";
+}
+
+function overallStatus(statuses) {
+  if (statuses.includes("EFFICIENCY_REGRESSION")) return "EFFICIENCY_REGRESSION";
+  if (statuses.includes("NOT_COMPARABLE")) return "NOT_COMPARABLE";
+  if (statuses.length === 0 || statuses.every((status) => status === "NOT_MEASURED")) return "NOT_MEASURED";
+  return "OK";
+}
+
+function helpText() {
+  return "Usage: npm run benchmark:profiles:regression -- [--results <directory>] [--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));
+  const reports = [];
+  for (const runSet of runSets) {
+    for (const scenario of scenarios) {
+      const runs = runSet.runs.filter((run) => run.scenarioId === scenario.scenarioId);
+      if (runs.length === 0) {
+        reports.push({ runSetId: runSet.runSetId, scenarioId: scenario.scenarioId, status: "NOT_COMPARABLE" });
+        continue;
+      }
+      const aggregate = aggregateBenchmarkRuns({ scenario, runs });
+      reports.push({
+        runSetId: runSet.runSetId,
+        scenarioId: scenario.scenarioId,
+        expectedProfile: scenario.expectedProfile,
+        status: statusForAggregate(aggregate, runs),
+        claimsAllowed: aggregate.claimsAllowed,
+        contextInflation: aggregate.contextInflation?.status ?? null,
+      });
+    }
+  }
+  const status = overallStatus(reports.map((report) => report.status));
+  const output = {
+    status,
+    blocking: false,
+    runSetCount: runSets.length,
+    scenarioCount: scenarios.length,
+    reports,
+    policy: "EFFICIENCY_REGRESSION is an observational release-quality warning and never a ForgeLoop lifecycle failure.",
+  };
+  if (options.json) console.log(JSON.stringify(output));
+  else {
+    console.log(`Efficiency regression status: ${status}`);
+    console.log(`Run sets: ${runSets.length}`);
+    console.log("This report is observational and does not change lifecycle completion.");
+  }
+}
+
+main().catch((error) => {
+  console.error(`ForgeLoop efficiency regression check: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/generate-agent-protocol-summary.mjs

@@ -79,6 +79,41 @@ Package version: ${packageJson.version}
 6. Run forgeloop complete; accept completion only when the validator returns VALID.
 7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
 
+## Adaptive execution profiles
+
+\`complianceMode\` controls how strongly project policy is enforced. The
+orthogonal \`executionProfile\` controls process and context depth: \`auto\`
+resolves deterministically to \`light\`, \`balanced\`, or \`full\` from route,
+contract, and task metadata. CLI requests take precedence over project
+configuration, but a safety floor always wins. Profiles never remove required
+contracts, gates, verification, provenance, lifecycle phases, or validated
+completion. Protocol-v1 routes without the field project to \`balanced\` for
+compatibility without rewriting historical artifacts.
+
+For \`light\` tasks, hosts should use \`next --compact\` or \`task-show --compact\`,
+load only relevant guide sections, keep plans concise, and avoid optional
+reflection, trajectory evaluation, handoff, attestation, and continuity
+artifacts unless requested, required, or needed for recovery. The lifecycle
+chronology remains unchanged.
+
+The read-only \`task/context\` integration resource provides the canonical
+profile-aware projection: objective, deliverables, constraints, selected guide
+IDs, phase, next action, verification requirements, and context policy. A
+profile changes presentation and optional context only; it never permits a
+phase or required gate to be skipped.
+
+Usage telemetry is provider or host reported when available, actor-reported
+only through the explicit \`usage-record\` fallback, and \`UNKNOWN\` otherwise.
+ForgeLoop never estimates tokens or treats usage as verification evidence.
+\`efficiency --task\` is read-only and returns \`NOT_COMPARABLE\` unless a
+project-local baseline has matching metadata.
+
+Measured execution-profile benchmarks are observational. The reproducible
+runner accepts provider or host usage, records actual timing, requires PASS
+verification and matching metadata for comparisons, and reports \`NOT_MEASURED\`
+or \`NOT_COMPARABLE\` when evidence is absent or incompatible. See
+\`docs/EXECUTION_PROFILE_BENCHMARKS.md\` for the runner and schemas.
+
 ## Authority boundaries
 
 - Protocol-derived facts outrank actor-provided labels, free-form summaries, and guessed identities.