@cassiomc1/forgeloop 1.6.5 → 1.8.0

package/docs/EXECUTION_PROFILE_BENCHMARKS.md

@@ -0,0 +1,420 @@
+# 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
+```
+
+Repetition counts are bounded by an explicit tier so the statistical purpose
+of a run set is visible in the command itself:
+
+| Tier | Runs | Purpose |
+| --- | --- | --- |
+| `smoke` | 1–3 | Fast adapter and pipeline checks; never efficiency evidence. |
+| `evidence` | 5–10 | Central-tendency comparisons (default when no tier is given: 5 runs). |
+| `tail` | 20–30 | Tail-risk and P95 stability analysis. |
+
+`--tier smoke|evidence|tail` enforces these bounds and selects the tier
+default when `--runs` is omitted. Runs outside a tier's bounds are rejected.
+Tail-stability conclusions additionally require the sample minimum described
+under tail analysis below.
+
+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,
+    diagnostics: {
+      executionProfile: "light",
+      verificationCycles: 1,
+      modelTurns: 3,
+      toolCalls: 5,
+      retries: null,
+      correctionCycles: null,
+      filesRead: null,
+      filesWritten: 2,
+      contextRefreshes: null,
+      guideCount: 1,
+      guideIds: ["test"],
+      hostWarnings: [],
+      terminationReason: "COMPLETED",
+      flags: [],
+    },
+  };
+}
+```
+
+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.
+
+The optional `diagnostics` object records host-observed execution detail for
+tail-risk attribution. Every field is nullable: a host must leave a value
+`null` (or omit `diagnostics` entirely) whenever it does not actually observe
+that telemetry, and must never estimate it from prompt size, elapsed time, or
+file size. `flags` may carry host-reported runaway signals from the fixed
+signal vocabulary; the aggregate additionally derives deterministic signals
+where recorded diagnostics support them.
+
+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.
+
+## Blind UI quality finalization
+
+The runner supports an optional post-run finalization hook for adapters that
+can collect independent UI evidence:
+
+```js
+export async function finalizeBenchmark({ benchmarkVersion, records, scenarios, target, runSetId }) {
+  // Render and evaluate retained UI workspaces after all host timings finish.
+  return {
+    qualityByRunId: {
+      // Keys are the runner-owned run IDs; values use the quality shape above.
+    },
+    summary: { status: "MEASURED" },
+  };
+}
+```
+
+The runner calls this hook only after every `runBenchmark` call has returned.
+The adapter's `wallClockMs` therefore excludes browser rendering and evaluator
+latency. The finalizer may attach quality only to known runner run IDs; usage,
+timing, verification, comparable steps, context telemetry, and metadata are
+not rewritten by finalization. A finalizer must leave quality `UNKNOWN` when a
+candidate cannot be rendered or the evaluator cannot return schema-valid
+scores.
+
+The maintained Codex visual evaluator is intentionally outside ForgeLoop
+Core. It requires an explicitly supplied, already-installed Playwright runtime
+and Chromium executable, renders desktop (1440×900) and mobile (390×844)
+screenshots, blocks HTTP(S) requests, and gives the separate evaluator only
+requirements, neutral browser observations, and anonymized candidate labels.
+The evaluator receives no execution-mode labels, run IDs, source files, or
+implementer self-ratings. Its validated scores are recorded as
+`EXTERNAL_REPORTED`; this is independent observational evidence, not a human
+acceptance decision and not lifecycle authority. If the evaluator is not
+configured or fails, quality remains `UNKNOWN` and no quality-preservation
+claim is permitted.
+
+## Inspecting and validating results
+
+```bash
+npm run benchmark:profiles:summary -- --json
+npm run benchmark:profiles:check -- --json
+npm run benchmark:profiles:outliers -- --json
+```
+
+To enable the optional blind UI finalizer, provide paths to the host's
+existing Playwright and Chromium installations and a separate evaluator
+model. The benchmark does not install these resources:
+
+```bash
+FORGELOOP_BENCHMARK_MODEL=gpt-5.4-mini \
+FORGELOOP_BENCHMARK_REASONING=low \
+FORGELOOP_BENCHMARK_QUALITY_EVALUATOR=./benchmarks/evaluators/codex-cli-blind-visual.mjs \
+FORGELOOP_BENCHMARK_PLAYWRIGHT_ROOT=/absolute/path/to/playwright \
+FORGELOOP_BENCHMARK_BROWSER=/absolute/path/to/Google\ Chrome\ for\ Testing \
+FORGELOOP_BENCHMARK_EVALUATOR_MODEL=gpt-5.4 \
+npm run benchmark:profiles -- \
+  --adapter ./benchmarks/adapters/codex-cli-real-host.mjs \
+  --runs 5 \
+  --run-set codex-quality-repeat5-YYYYMMDD \
+  --output /tmp/forgeloop-benchmark-results-quality \
+  --json
+```
+
+The two evaluator processes have separate responsibilities: the
+implementation host reports actual usage and deterministic verification, and
+the read-only evaluator reports blind screenshot scores. Neither process may
+invent context-item counts, token counts, costs, cache values, or lifecycle
+state.
+
+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.
+
+## Robust statistics and tail stability
+
+Benchmark methodology v2 reports robust variability for skewed token
+distributions. Methodology-v2 mode aggregates include, for every measured
+quantity, `count`, `average`, `minimum`, `p25`, `p50`, `p75`, `p90`, `p95`,
+`maximum`, `iqr`, `mad`, and `outlierCount`. Percentiles use linear
+interpolation; `iqr` is the interquartile range and `mad` the median absolute
+deviation around the median. Methodology-v1 aggregates keep their frozen
+historical shape.
+
+Every non-direct comparison in a v2 aggregate gains a `tail` object, `pairedRatioDiagnostics`, `pairedRuns`, and separate paired and distribution statistics:
+
+```json
+{
+  "pairedOverheadPercent": {
+    "p50": 3.5685,
+    "p95": 174.1502
+  },
+  "distributionDeltaPercent": {
+    "p50": 3.4708,
+    "p95": 13.1906
+  },
+  "pairedRatioDiagnostics": {
+    "pairCount": 20,
+    "baselineMinimum": 63298,
+    "baselineP25": 65742.25,
+    "baselineP50": 140632,
+    "lowBaselineThreshold": 84379.2,
+    "lowBaselinePairCount": 7
+  },
+  "tail": {
+    "sampleMinimum": 20,
+    "sampleCount": 20,
+    "p95TokenOverheadPercent": 174.1502,
+    "pairedOverheadP95Percent": 174.1502,
+    "distributionP95DeltaPercent": 13.1906,
+    "outlierCount": 0,
+    "status": "TAIL_REGRESSION",
+    "pairedStatus": "TAIL_REGRESSION",
+    "distributionStatus": "TAIL_ACCEPTABLE",
+    "combinedInterpretation": "TAIL_PAIRED_RATIO_SENSITIVE"
+  }
+}
+```
+
+### Paired overhead vs. distribution tail delta
+
+`pairedOverheadP95Percent` is the P95 of run-level relative overhead values (`((adaptive_i - direct_i) / direct_i) * 100`) across matched run indices. Because execution runs are independent stochastic trials, paired ratios can become very large when an individual direct baseline run finishes in an unusually low token regime (`LOW_BASELINE_TOKEN_REGIME`, defined as `directTokens < directP50 * 0.60`).
+
+`distributionP95DeltaPercent` compares the P95 values of the candidate and baseline token distributions directly (`((adaptiveP95 - directP95) / directP95) * 100`).
+
+These are distinct statistics and must not be presented as interchangeable metrics:
+
+- When a candidate distribution is genuinely heavy-tailed, `distributionP95DeltaPercent` itself exceeds the objective (`TAIL_DISTRIBUTION_REGRESSION`).
+- When the candidate distribution P95 is acceptable but paired overhead is inflated by low-baseline runs, the combined interpretation is `TAIL_PAIRED_RATIO_SENSITIVE`.
+
+```bash
+npm run benchmark:profiles:tail-analysis -- [--results <dir>] [--run-set <id>] [--json]
+```
+
+Tail status is observational and is classified as:
+
+- `NOT_ENOUGH_SAMPLES` when comparable pairs are below the sample minimum (20) or P95 telemetry is unavailable;
+- `TAIL_REGRESSION` when the P95 token metric exceeds the +60% objective;
+- `TAIL_WARNING` when the sample is sufficient but IQR outliers are present;
+- `TAIL_STABLE` / `TAIL_ACCEPTABLE` otherwise.
+
+Combined interpretation states:
+
+- `TAIL_CONSISTENT`: paired and distribution views agree;
+- `TAIL_PAIRED_RATIO_SENSITIVE`: paired P95 fails while distribution P95 passes and low-baseline pairs are present;
+- `TAIL_DISTRIBUTION_REGRESSION`: absolute distribution P95 delta exceeds the objective;
+- `TAIL_UNRESOLVED`: sample count is insufficient or evidence is incomplete.
+
+Tail status never gates lifecycle completion; it tells operators when a run
+set is large enough to trust its tail.
+
+## Outlier classification and runaway signals
+
+Token outliers are classified deterministically per scenario and mode with
+the `TOKEN_IQR_1_5` policy: a measured run whose total tokens exceed
+`Q3 + 1.5 × IQR` of that mode's measured distribution is an outlier, and at
+least 4 measured samples are required before classification. Each outlier
+record keeps the run identity, token values, `ratioToMedian`, and the
+diagnostic signals that explain it.
+
+```bash
+npm run benchmark:profiles:outliers -- [--results <dir>] [--run-set <id>] [--json]
+```
+
+The report is read-only: it never rewrites raw runs or aggregates and it
+never changes lifecycle truth. Signals come from two sources: host-reported
+`diagnostics.flags` and deterministic derivations from recorded diagnostics
+(model turns or tool calls more than double the mode median, repeated
+verification or correction cycles, retries, repeated context refreshes). An
+outlier with no recorded explanation is reported as `UNKNOWN_TOKEN_SPIKE`,
+which is an admission of missing telemetry, not an estimate. Historical
+methodology-v1 runs carry no diagnostics, so their spikes legitimately remain
+`UNKNOWN_TOKEN_SPIKE`.
+
+## Methodology versioning and historical compatibility
+
+Scenarios, runs, and aggregates carry a `benchmarkVersion`. Methodology v2
+bumps the current version to `2`; readers accept versions `1` and `2`.
+Historical v1 run sets are immutable evidence: their raw runs and stored
+aggregates are never rewritten, and recomputation reproduces the frozen v1
+aggregate shape exactly. Version checks therefore never invalidate committed
+history; a run set aggregates under the methodology its runs were measured
+with. Only new run sets recorded under methodology v2 receive robust
+statistics, tail status, outlier analysis, and diagnostics.
+
+## 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.

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.
@@ -113,7 +119,7 @@ forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
 
 | Component | Current contract |
 | --- | --- |
-| ForgeLoop core package | `>=1.5.0 <2` dependency range; current repository generation `1.6.x` |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current repository generation `1.8.x` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |

package/docs/RELEASE_CHECKLIST.md

@@ -16,6 +16,17 @@ 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 benchmark:profiles:outliers` and
+      `npm run benchmark:profiles:tail-analysis` report the observed
+      `TOKEN_IQR_1_5`, paired-ratio, and distribution-tail results without
+      conflating `pairedOverheadPercent` with `distributionDeltaPercent`.
+- [ ] Historical v1 run sets remain byte-for-byte immutable while v2 run sets
+      carry robust statistics, low-baseline diagnostics, and explicit tail
+      interpretations.
 - [ ] `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.5",
+  "version": "1.8.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "src",
     "ENG",
     "schemas",
+    "benchmarks/execution-profiles",
     ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
@@ -65,8 +66,16 @@
     "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/report-execution-profile-outliers.mjs",
+    "scripts/report-tail-interpretation.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",
@@ -104,7 +113,13 @@
     "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:outliers": "node scripts/report-execution-profile-outliers.mjs",
+    "benchmark:profiles:tail-analysis": "node scripts/report-tail-interpretation.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 } },