@cassiomc1/forgeloop 1.6.4 → 1.7.0

package/completions/forgeloop.fish

@@ -1,5 +1,5 @@
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
-complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor eval handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
+complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'action' -d 'durable action ID'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'approval' -d 'current fingerprint-bound approval'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'help' -d 'show this help'
@@ -161,6 +161,12 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from doctor' -l 'json' -d 'e
 complete -c forgeloop -f -n '__fish_seen_subcommand_from doctor' -l 'path' -d 'target project directory (default: current directory)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from doctor' -l 'strict' -d 'treat warnings as unhealthy'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from doctor' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'baseline' -d 'optional comparable efficiency baseline JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'json' -d 'emit efficiency metrics as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from efficiency' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'json' -d 'emit evaluation as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'path' -d 'target project directory (default: current directory)'
@@ -220,6 +226,7 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'j
 complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'path' -d 'target project directory (default: current directory)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'to' -d 'target supported protocol version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from migrate-protocol' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'compact' -d 'emit a bounded next-action projection'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'json' -d 'emit structured output as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from next' -l 'path' -d 'target project directory (default: current directory)'
@@ -388,6 +395,7 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from responsibility-status'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from responsibility-status' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'behavior-change' -d 'declare behavior change'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'executable-change' -d 'declare executable/configuration change'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'execution-profile' -d 'requested execution profile; safety floors always win'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'json' -d 'emit route result as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from route' -l 'path' -d 'target project directory (default: current directory)'
@@ -480,6 +488,7 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from task-scope' -l 'json' -
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-scope' -l 'path' -d 'target project directory (default: current directory)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-scope' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-scope' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from task-show' -l 'compact' -d 'emit a bounded task-status projection'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-show' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-show' -l 'json' -d 'emit structured output as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from task-show' -l 'path' -d 'target project directory (default: current directory)'
@@ -501,6 +510,20 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from update' -l 'dry-run' -d
 complete -c forgeloop -f -n '__fish_seen_subcommand_from update' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from update' -l 'path' -d 'target project directory (default: current directory)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from update' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'cache-read-tokens' -d 'provider-reported cache-read token count'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'cache-write-tokens' -d 'provider-reported cache-write token count'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'cost-usd' -d 'provider-reported cost in USD; never estimated'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'input-tokens' -d 'provider-reported input token count'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'json' -d 'emit usage telemetry as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'model' -d 'model name reported by the actor'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'output-tokens' -d 'provider-reported output token count'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'provider' -d 'provider name reported by the actor'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'source' -d 'usage source; CLI fallback accepts only ACTOR_REPORTED'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'total-tokens' -d 'provider-reported total token count; never estimated'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from usage-record' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from validate-protocol' -l 'continuity-file' -d 'optional execution-continuity JSON relative to target'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from validate-protocol' -l 'contract-file' -d 'current JSON contract used for freshness comparison'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from validate-protocol' -l 'delegated-result-file' -d 'delegated result JSON file'

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.6.4
+Package version: 1.7.0
 
 ## Canonical loop
 
@@ -19,6 +19,41 @@ Package version: 1.6.4
 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.
@@ -38,14 +73,19 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 
 | Feature | Version | Supported |
 | --- | --- | --- |
+| adaptiveExecutionProfiles | 1 | yes |
 | canonicalHandoffs | 1 | yes |
 | capabilityPolicy | 1 | yes |
 | codeAttestation | 1 | yes |
+| compactLifecycleOutput | 1 | yes |
+| contextUsageObservability | 1 | yes |
 | diagnostics | n/a | yes |
 | differentialVerificationScope | 1 | yes |
 | durableActions | 1 | yes |
 | durableApprovals | 1 | yes |
+| efficiencyMetrics | 1 | yes |
 | executionHistory | 1 | yes |
+| executionProfileContext | 1 | yes |
 | integrationApi | 1 | yes |
 | observabilityStability | n/a | yes |
 | reflection | 1 | yes |
@@ -55,6 +95,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | taskInspection | 1 | yes |
 | trajectoryEvaluation | 1 | yes |
 | trajectoryMetrics | 1 | yes |
+| usageTelemetry | 1 | yes |
 | verificationExecutionIsolation | 1 | yes |
 | workspaceBinding | 1 | yes |
 
@@ -90,6 +131,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | session | SESSION | .forgeloop/sessions/<session-id>.json | activation | SESSION_MARKER |
 | sources | PROJECT | .forgeloop/sources.json | source-registry | SOURCE_ATTESTATION |
 | state | TASK | .forgeloop/task-state/<task-key>/work-state.json | work-state | CANONICAL_LIFECYCLE_STATE |
+| usage | TASK | .forgeloop/task-state/<task-key>/usage.json | usage | INFORMATIONAL_USAGE_TELEMETRY |
 | verificationScope | TASK | .forgeloop/task-state/<task-key>/verification-scope.json | verification-scope | VERIFICATION_SCOPE_PLAN |
 | workspaceBinding | TASK | .forgeloop/task-state/<task-key>/workspace-binding.json | workspace-binding | WORKSPACE_IDENTITY_BINDING |
 
@@ -135,6 +177,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | Command | Mutation | Purpose |
 | --- | --- | --- |
 | doctor | MUTATING | Diagnoses project health, discovers adapters, and optionally repairs missing template files. |
+| efficiency | READ_ONLY | Projects usage and timing efficiency, comparing only against a metadata-compatible local baseline. |
 | eval | MUTATING | Evaluates the current trajectory against a validated project-local reference scenario. |
 | history | READ_ONLY | Shows chronological protocol history reconstructed from canonical ForgeLoop state. |
 | inspect | READ_ONLY | Inspects target repository health, dirty files, active branch, and artifact freshness. |
@@ -145,6 +188,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | reflect | READ_ONLY | Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation. |
 | status | READ_ONLY | Displays current lifecycle phase, active checks, blockers, and artifact freshness bindings. |
 | trace | READ_ONLY | Emits detailed structured task trace with provenance and artifact relationships. |
+| usage-record | MUTATING | Records actor-reported usage telemetry without treating it as verification evidence. |
 | validate-protocol | READ_ONLY | Validates end-to-end cryptographic freshness, fingerprint bindings, and ledger integrity. |
 | validate-state | READ_ONLY | Validates schema adherence and internal consistency of work-state.json. |
 

package/docs/ARTIFACT_REFERENCE.md

@@ -35,6 +35,7 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `task-state/<task-key>/approvals/approval-<id>.json` | `approval` | Protocol Managed | Append Decision Once | Action Approval Attestation |
 | `policy/capabilities.json` | `capability-policy` | Operator Or Agent | Mutable Configuration | Capability Policy Specification |
 | `task-state/<task-key>/evaluations/eval-<id>.json` | `trajectory-evaluation` | Protocol Compiled | Immutable Once Written | Trajectory Evaluation |
+| `task-state/<task-key>/usage.json` | `usage` | Actor Or Trusted Host | Overwritten On Usage Record | Informational Usage Telemetry |
 | `task-state/<task-key>/workspace-binding.json` | `workspace-binding` | Protocol Generated | Immutable After Bind | Workspace Identity Binding |
 | `task-state/<task-key>/handoffs/handoff-<id>.json` | `handoff-envelope` | Protocol Compiled | Immutable Once Written | Canonical Handoff Snapshot |
 | `task-state/<task-key>/responsibility.json` | `responsibility` | Agent Or Harness Constrained | Immutable During Pass | Responsibility Constraint |
@@ -110,6 +111,14 @@ The operational task specification authored before execution begins.
 
 The deterministic result of routing task signals against the engineering guide router.
 
+New routes include a deterministic `executionProfile`. It is separate from
+the project `complianceMode`: the profile controls context/process depth while
+compliance controls enforcement. The persisted route is authoritative for the
+resolved profile and is included in route fingerprints. Historical protocol-v1
+routes may omit this optional field and remain readable; consumers project
+missing profile metadata to `balanced` compatibility behavior without rewriting
+the historical artifact.
+
 #### Canonical Fields
 
 <!-- BEGIN FORGELOOP GENERATED: schema:routing-result -->
@@ -117,6 +126,12 @@ The deterministic result of routing task signals against the engineering guide r
 - `schemaVersion` *(number, required, const: 1)*
 - `protocolVersion` *(number, required, const: 1)*
 - `contractFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `executionProfile` *(object, optional)*
+  - `requested` *(string, required, enum: `auto`, `light`, `balanced`, `full`)*
+  - `floor` *(string, required, enum: `light`, `balanced`, `full`)*
+  - `resolved` *(string, required, enum: `light`, `balanced`, `full`)*
+  - `reasons` *(array<string>, required, minItems: 1)*
+  - `escalated` *(boolean, required)*
 - `input` *(object, required)*
 - `primary` *(string or null, required)*
 - `guides` *(array<string>, required)*
@@ -231,6 +246,7 @@ Local ForgeLoop configuration settings and policy bindings.
 - `schemaVersion` *(number, required, const: 1)*
 - `protocolVersion` *(number, required, const: 1)*
 - `complianceMode` *(string, required, enum: `advisory`, `standard`, `strict`)*
+- `executionProfile` *(string, optional, enum: `auto`, `light`, `balanced`, `full`)*
 - `policy` *(string, optional, minLength: 1)*
 - `requiredGates` *(array<string>, optional)*
 - `requiredEvidence` *(array<string>, optional)*
@@ -830,7 +846,37 @@ evidence and never override lifecycle validation.
 
 <!-- END FORGELOOP GENERATED: schema:trajectory-evaluation -->
 
-### 2.24 `task-state/<taskKey>/workspace-binding.json`
+### 2.24 `task-state/<taskKey>/usage.json`
+
+<!-- forgeloop-doc: schema=usage artifact=.forgeloop/task-state/<task-key>/usage.json -->
+
+Optional task-scoped usage telemetry. Provider and host reports cross the
+trusted runtime boundary; the CLI fallback remains explicitly
+`ACTOR_REPORTED`. Usage is informational and never acts as verification
+evidence.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:usage -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `recordedAt` *(string, required, minLength: 1)*
+- `usage` *(object, required)*
+  - `inputTokens` *(integer,null, required, minimum: 0)*
+  - `outputTokens` *(integer,null, required, minimum: 0)*
+  - `cacheReadTokens` *(integer,null, required, minimum: 0)*
+  - `cacheWriteTokens` *(integer,null, required, minimum: 0)*
+  - `totalTokens` *(integer,null, required, minimum: 0)*
+  - `costUsd` *(number,null, required, minimum: 0)*
+  - `model` *(string,null, required)*
+  - `provider` *(string,null, required)*
+  - `source` *(string, required, enum: `PROVIDER_REPORTED`, `HOST_REPORTED`, `ACTOR_REPORTED`, `UNKNOWN`)*
+
+<!-- END FORGELOOP GENERATED: schema:usage -->
+
+### 2.25 `task-state/<taskKey>/workspace-binding.json`
 
 <!-- forgeloop-doc: schema=workspace-binding artifact=.forgeloop/task-state/<task-key>/workspace-binding.json -->
 
@@ -855,7 +901,7 @@ does not fabricate a binding when absent.
 
 <!-- END FORGELOOP GENERATED: schema:workspace-binding -->
 
-### 2.25 `task-state/<taskKey>/handoffs/handoff-<id>.json`
+### 2.26 `task-state/<taskKey>/handoffs/handoff-<id>.json`
 
 <!-- forgeloop-doc: schema=handoff-envelope artifact=.forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json -->
 
@@ -895,7 +941,7 @@ completion, or authority evidence.
 
 <!-- END FORGELOOP GENERATED: schema:handoff-envelope -->
 
-### 2.26 `task-state/<taskKey>/responsibility.json`
+### 2.27 `task-state/<taskKey>/responsibility.json`
 
 <!-- forgeloop-doc: schema=responsibility artifact=.forgeloop/task-state/<task-key>/responsibility.json -->
 
@@ -926,7 +972,7 @@ and completion boundaries.
 
 <!-- END FORGELOOP GENERATED: schema:responsibility -->
 
-### 2.27 `task-state/<taskKey>/verification-scope.json`
+### 2.28 `task-state/<taskKey>/verification-scope.json`
 
 <!-- forgeloop-doc: schema=verification-scope artifact=.forgeloop/task-state/<task-key>/verification-scope.json -->
 
@@ -958,7 +1004,7 @@ otherwise it resolves to `FULL`. ForgeLoop does not publish a heuristic
 
 <!-- END FORGELOOP GENERATED: schema:verification-scope -->
 
-### 2.28 `task-state/<taskKey>/attestations/code-manifest.json`
+### 2.29 `task-state/<taskKey>/attestations/code-manifest.json`
 
 <!-- forgeloop-doc: schema=code-manifest artifact=.forgeloop/task-state/<task-key>/attestations/code-manifest.json -->
 
@@ -999,7 +1045,7 @@ represented by provider identities, and `.forgeloop/**` is excluded.
 
 <!-- END FORGELOOP GENERATED: schema:code-manifest -->
 
-### 2.29 `task-state/<taskKey>/attestations/statement.json`
+### 2.30 `task-state/<taskKey>/attestations/statement.json`
 
 <!-- forgeloop-doc: schema=in-toto-statement artifact=.forgeloop/task-state/<task-key>/attestations/statement.json -->
 
@@ -1022,7 +1068,7 @@ back-reference itself from the execution receipt.
 
 <!-- END FORGELOOP GENERATED: schema:in-toto-statement -->
 
-### 2.30 `task-state/<taskKey>/attestations/statement.sigstore.json`
+### 2.31 `task-state/<taskKey>/attestations/statement.sigstore.json`
 
 <!-- forgeloop-doc: external-artifact=.forgeloop/task-state/<task-key>/attestations/statement.sigstore.json -->
 

package/docs/CLI_REFERENCE.md

@@ -31,6 +31,25 @@ ForgeLoop uses a definition-driven command-line parser:
 - **Boolean Flags**: Never accept inline values (e.g. `--json=false` is rejected).
 - **Argv Passthrough**: Everything after a command's `--` passthrough marker is preserved exactly and is not parsed as ForgeLoop syntax.
 
+### Execution profile and compact context
+
+`route` resolves the orthogonal execution profile from `auto`, `light`,
+`balanced`, or `full`. CLI requests take precedence over project configuration,
+but a deterministic safety floor always wins. The profile changes context and
+process depth only; it never bypasses lifecycle phases, gates, verification,
+authority, provenance, or completion validation.
+
+For high-frequency host reads, request bounded projections:
+
+```bash
+forgeloop next --task <id> --compact --json
+forgeloop task-show --task <id> --compact --json
+```
+
+Compact output always preserves task identity, phase, resolved profile,
+required next action or status, terminal state where applicable, and blocker
+error codes. Default output and default JSON remain unchanged.
+
 ---
 
 ## Command Index by Purpose
@@ -39,7 +58,7 @@ ForgeLoop uses a definition-driven command-line parser:
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
@@ -476,6 +495,60 @@ only exact argv. Caller-reported and externally observed provenance are not host
 
 <!-- END FORGELOOP GENERATED: cli:metrics:options -->
 
+### `usage-record`
+
+Records optional actor-reported usage telemetry for a task. This data is
+informational and never satisfies verification or completion requirements.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:usage-record:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--provider <name>`: provider name reported by the actor
+- `--model <name>`: model name reported by the actor
+- `--input-tokens <number>`: provider-reported input token count
+- `--output-tokens <number>`: provider-reported output token count
+- `--cache-read-tokens <number>`: provider-reported cache-read token count
+- `--cache-write-tokens <number>`: provider-reported cache-write token count
+- `--total-tokens <number>`: provider-reported total token count; never estimated
+- `--cost-usd <amount>`: provider-reported cost in USD; never estimated
+- `--source <kind>`: usage source; CLI fallback accepts only ACTOR_REPORTED
+- `--json`: emit usage telemetry as JSON
+
+<!-- END FORGELOOP GENERATED: cli:usage-record:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop usage-record --task task-001 --provider provider --model provider/model --input-tokens 10000 --output-tokens 2500 --source ACTOR_REPORTED --json
+  ```
+
+  The CLI fallback is always actor-reported. It never promotes the source to a
+  provider or host observation and never satisfies verification evidence.
+
+### `efficiency`
+
+Projects timing and usage efficiency. Comparisons are reported only when the
+project-local baseline metadata is compatible with the current task.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:efficiency:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--baseline <path>`: optional comparable efficiency baseline JSON
+- `--json`: emit efficiency metrics as JSON
+
+<!-- END FORGELOOP GENERATED: cli:efficiency:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop efficiency --task task-001 --baseline benchmark-baseline.json --json
+  ```
+
+  A missing or metadata-incompatible baseline produces `NOT_COMPARABLE` and
+  null comparison values; ForgeLoop does not estimate token or time overhead.
+
 ### `eval`
 
 <!-- BEGIN FORGELOOP GENERATED: cli:eval:options -->
@@ -631,6 +704,7 @@ Calculates and persists deterministic engineering guide routing.
 - `--platform <value>`: affected platform (repeatable)
 - `--behavior-change`: declare behavior change
 - `--executable-change`: declare executable/configuration change
+- `--execution-profile <profile>`: requested execution profile; safety floors always win
 - `--json`: emit route result as JSON
 
 <!-- END FORGELOOP GENERATED: cli:route:options -->
@@ -641,6 +715,12 @@ Calculates and persists deterministic engineering guide routing.
   forgeloop route --work complete-website --surface ui --risk untrusted-input --json
   ```
 
+  A requested profile is an override request, not a safety bypass:
+
+  ```bash
+  forgeloop route --task landing-page --work complete-website --surface ui --execution-profile light --json
+  ```
+
 ### `preflight`
 
 Validates pre-implementation readiness and establishes protocol readiness state.
@@ -752,6 +832,7 @@ Computes the deterministic next action required by the protocol.
 
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--compact`: emit a bounded next-action projection
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:next:options -->
@@ -1751,6 +1832,7 @@ Displays details of a specific task by ID or storage key.
 
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--compact`: emit a bounded task-status projection
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-show:options -->

package/docs/EXECUTION_PROFILE_BENCHMARKS.md

@@ -0,0 +1,208 @@
+# Execution-profile benchmark protocol
+
+ForgeLoop keeps execution-profile efficiency evidence separate from lifecycle
+trust. The benchmark scenarios under
+[`benchmarks/execution-profiles/`](../benchmarks/execution-profiles/) are
+deterministic routing specifications. They are not measurements and they do
+not authorize a performance claim by themselves.
+
+## What is measured
+
+The runner executes every scenario in these modes:
+
+| Mode | Meaning |
+| --- | --- |
+| `direct` | The direct baseline supplied by the host adapter. |
+| `forgeloopBalanced` | The normal ForgeLoop context and process presentation. |
+| `forgeloopAdaptive` | The deterministic profile resolved from the scenario, contract, and scope. |
+
+Each run records provider or host usage, runner-measured wall-clock time,
+verification outcome, verification cycles, comparable work steps, and the
+metadata needed to determine whether a comparison is valid. The runner never
+derives token counts, costs, cache values, verification results, or comparable
+steps from prompt length, elapsed time, model names, or estimates.
+
+The required reference set contains the six original scenarios plus
+`novatask-saas-landing-page`: documentation correction, static landing page,
+small bug fix, API feature, authentication change, infrastructure/release, and
+the NovaTask static SaaS landing page. NovaTask is a local HTML5/CSS3/vanilla
+JavaScript workload with no external services, authentication, secrets, or
+publication, and must resolve to `light`.
+
+Trusted efficiency comparisons require all of the following:
+
+- `PROVIDER_REPORTED` or `HOST_REPORTED` usage;
+- actual non-null token and timing values for the metric being compared;
+- `PASS` verification for both paired runs;
+- a positive comparable-step count; and
+- matching model, provider, prompt-spec fingerprint, project revision,
+  benchmark version, and environment metadata.
+
+If any condition is missing, the aggregate reports `NOT_COMPARABLE` and
+`claimsAllowed: false` for that comparison. `UNKNOWN` is a valid telemetry
+state, not a zero value. Benchmark outcomes are observational and never relax
+the lifecycle, evidence, authority, provenance, safety-floor, or completion
+requirements.
+
+## Running a benchmark
+
+The command requires a host adapter because ForgeLoop cannot create real model
+or provider measurements on its own:
+
+```bash
+npm run benchmark:profiles -- \
+  --adapter ./path/to/actual-host-adapter.mjs \
+  --runs 5 \
+  --json
+```
+
+The adapter exports `runBenchmark(input)` and must execute the supplied
+scenario. Its result must include actual usage and verification data:
+
+```js
+export async function runBenchmark({ scenario, mode, runIndex, target }) {
+  // Execute the host's real workload here.
+  return {
+    usage: {
+      inputTokens: 120,
+      outputTokens: 80,
+      cacheReadTokens: null,
+      cacheWriteTokens: null,
+      totalTokens: 200,
+      costUsd: null,
+      model: "host-reported-model",
+      provider: "host-reported-provider",
+      source: "HOST_REPORTED",
+    },
+    promptSpecFingerprint: "sha256-or-other-host-bound-fingerprint",
+    verification: "PASS",
+    verificationCycles: 1,
+    comparableSteps: 4,
+  };
+}
+```
+
+The values above are shape-only examples. They must not be copied as evidence
+unless the host actually reports them. The runner owns the elapsed-time
+measurement and derives the Git revision from the target checkout. Results
+are written under a unique run-set directory and existing history is never
+overwritten.
+
+An adapter may also return host-observed context usage. ForgeLoop does not
+tokenize provider prompts. The optional shape is:
+
+```json
+{
+  "contextUsage": {
+    "source": "HOST_REPORTED",
+    "profile": "light",
+    "items": {
+      "taskContext": null,
+      "guides": null,
+      "history": null,
+      "protocolInstructions": null,
+      "repositoryContext": null,
+      "other": null
+    }
+  }
+}
+```
+
+Every item is nullable and `UNKNOWN` requires all items to remain `null`.
+Missing values are never inferred. When adaptive resolves to `light`, the
+aggregate compares complete host-reported context items with the matching
+balanced run and reports `CONTEXT_INFLATION` when light context is larger.
+This is an observational diagnostic and never blocks lifecycle completion.
+
+UI adapters may additionally return independently evaluated quality scores:
+
+```json
+{
+  "quality": {
+    "source": "EXTERNAL_REPORTED",
+    "scores": {
+      "visualQuality": null,
+      "responsiveQuality": null,
+      "accessibility": null,
+      "interactionPolish": null,
+      "requirementsCompleteness": null
+    }
+  }
+}
+```
+
+Scores are on a 0–5 scale and remain `UNKNOWN` when no external evaluator or
+host observation is available. Implementer self-ratings should not be used as
+independent quality evidence; for NovaTask, review direct and ForgeLoop
+outputs blind to execution mode before revealing the labels.
+
+## Inspecting and validating results
+
+```bash
+npm run benchmark:profiles:summary -- --json
+npm run benchmark:profiles:check -- --json
+```
+
+Before a host run exists, the summary is intentionally:
+
+```json
+{
+  "status": "NOT_MEASURED",
+  "claimsAllowed": false
+}
+```
+
+Raw runs are stored below `benchmarks/execution-profiles/results/raw/` and
+recomputed aggregates below `benchmarks/execution-profiles/results/aggregate/`.
+The validator checks all scenario, raw-run, and aggregate schemas and
+recomputes aggregates from raw measurements. A changed overhead target is
+observable in the report; it is not a blocking lifecycle gate.
+
+CI can run `npm run benchmark:profiles:regression -- --json`. It reports
+`OK`, `EFFICIENCY_REGRESSION`, `NOT_MEASURED`, or `NOT_COMPARABLE`; a regression
+is a release-quality warning, not a ForgeLoop lifecycle failure.
+
+For LIGHT scenarios, the initial non-blocking objectives are P50 token
+overhead no greater than +35% and P95 token overhead no greater than +60%
+against a comparable direct baseline. These objectives never trade away
+verification quality, requirement coverage, or protocol safety.
+
+## Host context contract
+
+The universal integration API exposes `task/context`, and the MCP adapter
+registers it as `forgeloop://task/{taskId}/context`. The projection includes
+the resolved profile, objective, deliverables, constraints, selected guide
+IDs, next action, verification requirements, and an explicit context policy:
+
+- `light`: targeted context, compact output, short planning, focused checks,
+  and lazy optional artifacts;
+- `balanced`: relevant context, standard output and planning, normal checks;
+- `full`: expanded context, deep planning, broad risk context, and expanded
+  verification when justified.
+
+Every projection also states that lifecycle phases, required gates, evidence,
+verification truth, authority, provenance, the safety floor, and validated
+completion remain unchanged. A host may omit optional presentation context,
+but it may not use `light` to skip a required lifecycle phase or gate.
+
+Historical protocol-v1 routes without profile metadata remain readable and are
+projected to the balanced compatibility profile.
+
+For UI scenarios, hosts should report independent visual, responsive,
+accessibility, interaction-polish, and requirements-completeness scores when
+an external evaluator or blind human review is available. Implementer
+self-ratings are not trusted as a substitute. NovaTask comparisons should
+hide the execution mode until this review is complete.
+
+## Schemas and source policy
+
+The machine-readable contracts are:
+
+- `schemas/execution-profile-benchmark-scenario.schema.json`;
+- `schemas/execution-profile-benchmark-run.schema.json`; and
+- `schemas/execution-profile-benchmark-aggregate.schema.json`.
+
+The source policy is intentionally narrow: provider or host observations are
+accepted for benchmark claims, while actor-reported or absent telemetry stays
+non-comparable. This is an efficiency observation boundary, not verification
+evidence and not an external publication result.