@cassiomc1/forgeloop 1.6.5 → 1.8.0

package/DOCS_INDEX.md

@@ -30,6 +30,7 @@ integration and guide context. Use this map before editing documentation.
 | Platform adapters | [`docs/PLATFORM_ADAPTERS.md`](./docs/PLATFORM_ADAPTERS.md) | Generic CI boundary and platform mapping guidance |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
+| Adaptive execution-profile benchmarks | [`docs/EXECUTION_PROFILE_BENCHMARKS.md`](./docs/EXECUTION_PROFILE_BENCHMARKS.md) | Measured provider/host runs, robust statistics, paired/distribution deltas, tail status, outliers, and profile-aware host context |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Current release checklist | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) | Package, protocol, attestation, integration, and publication gates |
 | ForgeLoop 1.6.1 release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |

package/GUIDE_ROUTER.md

@@ -237,7 +237,9 @@ The first routing contract is versioned as `schemaVersion: 1`. It accepts:
 - `surfaces`: `ui`, `forms`, `api`, `auth`, `data`, `database`, `mobile`,
   `desktop`, `game`, `video`, `ci`, `config`, `critical-path`, or `documentation`;
 - `risks`: `untrusted-input`, `personal-data`, `secrets`, `external-service`,
-  `publication`, `critical-path`, `performance`, or `accessibility`;
+  `publication`, `critical-path`, `performance`, `accessibility`, `destructive`,
+  `irreversible`, `production-deployment`, `credentials`, `payment`, or
+  `migration`;
 - `platforms`: `web`, `mobile`, `desktop`, `server`, `ci`, or
   `cross-platform`;
 - optional boolean `behaviorChange` and `executableChange` signals.
@@ -326,3 +328,26 @@ Verify Markdown, links, paths, commands, and examples.
 If investigation reveals a new surface, update the guide set before editing that area. Record only the concise reason; do not create a versioned task log.
 
 If an applicable guide is missing or inaccessible, use conservative defaults, do not invent its content, and disclose the limitation in the delivery.
+
+## Execution profile routing
+
+Guide selection and execution depth are separate deterministic decisions. The
+persisted route also contains `executionProfile` with `requested`, `floor`,
+`resolved`, `reasons`, and `escalated` fields. It is resolved from the same
+declared route signals plus contract and task-scope metadata; no model
+confidence, token estimate, or subjective complexity judgment is used.
+
+The safety floor is `light` for narrow low-risk documentation, copy, and local
+UI work; `balanced` for behavior or executable changes, ordinary application
+engineering, data/configuration/CI surfaces, and moderate scope; and `full`
+for authentication, critical paths, secrets, personal data, publication,
+infrastructure, destructive or irreversible operations, and authority-sensitive
+external mutations. A CLI request overrides project configuration only as a
+request: it cannot lower the resolved safety floor.
+
+Hosts should present `light` tasks with targeted guide sections, a compact
+plan, focused checks, and bounded `next --compact` or `task-show --compact`
+responses. Required gates, evidence, verification truth, lifecycle chronology,
+and validator-backed completion remain unchanged. Historical protocol-v1
+routes without the optional field remain valid and project to `balanced` for
+compatibility without being rewritten.

package/LOOP_ENGINEERING.md

@@ -19,6 +19,7 @@
 - [Project Discovery](#project-discovery)
 - [Capability Discovery & Authority](#capability-discovery-and-on-demand-extensions)
 - [Guide Selection](#guide-selection)
+- [Adaptive Execution Profiles](#adaptive-execution-profiles)
 - [Design & Implementation Gates](#design-and-implementation-gates)
 - [Proportional Planning](#proportional-planning)
 - [Execution Loop](#execution-loop)
@@ -69,6 +70,53 @@ If it discovered the ForgeLoop project adapter, evaluate capabilities:
 Never downgrade ForgeLoop to optional guidance solely because the runtime
 name is unknown.
 
+## Adaptive execution profiles
+
+ForgeLoop separates compliance policy from execution depth:
+
+- `complianceMode` (`advisory`, `standard`, `strict`) controls how strongly
+  project policy is enforced.
+- `executionProfile` (`auto`, `light`, `balanced`, `full`) controls how much
+  process and context depth is appropriate for the task.
+
+The default request is `auto`. ForgeLoop resolves it deterministically from
+route signals, the task contract, and task scope. A CLI request takes
+precedence over project configuration, and project configuration takes
+precedence over `auto`; the safety floor always wins. A low explicit request is
+escalated with a structured reason rather than treated as an error.
+
+`light` is intended for small, local, reversible, low-risk work. Hosts should
+use the smallest sufficient discovery, compact plans, targeted guide sections,
+focused verification, and `next --compact` or `task-show --compact`. It does
+not remove contracts, routes, preflight, required gates, verification truth,
+provenance, lifecycle phases, review, or validator-backed completion.
+
+`balanced` remains the normal profile for behavior changes, ordinary bugs,
+refactors, APIs, configuration, and moderate scope. `full` is required by
+authentication, secrets, personal data, publication, infrastructure,
+critical-path, destructive, irreversible, and authority-sensitive work.
+
+Optional reflection, trajectory evaluation, handoff, responsibility,
+attestation, benchmark, and continuity artifacts are lazy: they are created
+only when required by policy, requested by the user or host, or needed for
+recovery. The first profile release does not change lifecycle chronology or
+introduce a fast path.
+
+The profile-aware context projection is presentation guidance only. A host may
+use `task/context` to select targeted, normal, or expanded context, but a
+profile never authorizes skipping a lifecycle phase, required gate,
+verification requirement, authority check, provenance binding, safety floor,
+or validator-backed completion. A phase may be absent only when the canonical
+protocol determines that it is not applicable; it may never be omitted because
+the resolved profile is `light`.
+
+Usage telemetry is a separate informational domain. Only a trusted provider or
+host can report `PROVIDER_REPORTED` or `HOST_REPORTED`; the CLI fallback is
+explicitly `ACTOR_REPORTED`; absent data is `UNKNOWN`. ForgeLoop never
+estimates tokens, promotes actor data, or treats usage as verification
+evidence. `efficiency --task` reports comparisons only for a metadata-compatible
+project-local baseline.
+
 ### CLI-owned artifact policy
 
 Lifecycle-owned ForgeLoop artifacts must be created or mutated only through

package/ORCHESTRATOR_INTEGRATION.md

@@ -86,6 +86,44 @@ edited by hand.
 
 <!-- END FORGELOOP GENERATED: work-transitions -->
 
+## Profile-aware host behavior
+
+The host may adapt context and presentation depth after reading the resolved
+`executionProfile` from the persisted route or a compact task projection.
+`light` uses targeted guide sections, a compact plan, focused checks, and
+bounded lifecycle output; `balanced` keeps the normal relevant context; `full`
+permits broader risk and dependency context. The host must not reinterpret the
+profile or use it to skip lifecycle phases, required gates, verification
+requirements, authority checks, provenance, or completion validation.
+
+Hosts can consume the canonical `task/context` projection from the universal
+integration API (or `forgeloop://task/{taskId}/context` through MCP). It
+provides the objective, deliverables, constraints, selected guide IDs, next
+action, verification requirements, and the profile-specific presentation
+policy. A phase may be absent only when the canonical protocol says it is not
+applicable; `light` is never a reason to omit it.
+
+The profile changes context depth only. Required phases and gates, evidence and
+verification truth, authority and provenance, the safety floor, and
+validator-backed completion remain invariant.
+
+The canonical integration capability is `executionProfileContext`, and the
+host-facing `task/context` projection is the default input for profile-aware
+presentation. A host that cannot read that resource falls back to balanced
+compatibility behavior. It must consume `executionProfile.resolved`, preserve
+the safety floor, and pass missing context or usage as unavailable rather than
+estimating it.
+
+The profile is orthogonal to `complianceMode`. CLI requests take precedence
+over project configuration only as requests, while the deterministic safety
+floor always wins. Historical routes without the optional profile field remain
+readable and project to `balanced` compatibility behavior. The first release
+does not add a lifecycle fast path.
+
+Optional reflection, evaluation, handoff, responsibility, attestation,
+benchmark, and continuity artifacts are lazy. Create them only when required
+by policy, requested by the user or host, or needed for recovery.
+
 The host may skip proportional phases, but it must preserve the state
 invariants and record why a skipped phase was not applicable.
 

package/PROTOCOL_INTEGRATION.md

@@ -138,6 +138,68 @@ versions. A harness must not infer compatibility from the package version
 alone, and it must fail closed when its required protocol or schema version is
 absent from the relevant list.
 
+## Adaptive execution profiles and context presentation
+
+`complianceMode` and `executionProfile` are independent dimensions. Compliance
+mode (`advisory`, `standard`, or `strict`) describes enforcement policy;
+execution profile (`auto`, `light`, `balanced`, or `full`) describes process and
+context depth. ForgeLoop resolves the profile deterministically from route,
+contract, and task-scope metadata. CLI requests override project configuration
+as requests, but never lower the safety floor.
+
+Hosts may use the resolved profile to control presentation. For `light`, pass
+the objective, deliverables, constraints, profile, selected guide IDs, phase,
+next action, and verification requirements; reuse unchanged state locally and
+avoid reinjecting complete ledgers, schemas, receipts, and protocol documents.
+`next --compact` and `task-show --compact` provide bounded machine-readable
+projections. These presentation choices never alter required gates, evidence,
+verification truth, lifecycle chronology, authority, or validator-backed
+completion. A protocol-v1 route without profile metadata remains readable and
+projects to `balanced` compatibility behavior.
+
+The integration API also exposes the read-only `task/context` projection. It
+contains the resolved profile, objective, deliverables, constraints, selected
+guide IDs, next action, verification requirements, and a bounded context
+policy for hosts. A host may omit optional presentation context, but
+`light` never authorizes a skipped lifecycle phase or required gate. A phase
+may be absent only when the canonical protocol marks it not applicable.
+
+The capability handshake names this contract as `executionProfileContext` and
+marks `executionProfile.resolved` as authoritative. Historical consumers that
+do not expose `task/context` must use balanced compatibility behavior rather
+than inventing a local LIGHT heuristic. Optional benchmark context telemetry is
+host-reported or `UNKNOWN`; ForgeLoop does not tokenize provider prompts.
+
+The profile invariant block is explicit:
+
+```text
+execution depth changes presentation and optional context only.
+required lifecycle phases remain unchanged.
+required gates remain unchanged.
+verification truth and evidence requirements remain unchanged.
+authority, provenance, and safety-floor decisions remain unchanged.
+validator-backed completion remains unchanged.
+```
+
+Optional observability is lazy. Reflection, trajectory evaluation, handoff,
+responsibility, attestation, benchmark analysis, and continuity artifacts are
+not required merely because the capability exists; policy, user/host request,
+or recovery need must require them.
+
+Usage telemetry is a separate informational boundary. A runtime may supply an
+optional `ForgeLoopUsageProvider.getTaskUsage({ projectPath, taskId })`; the
+provider must report only `PROVIDER_REPORTED` or `HOST_REPORTED`. The CLI
+fallback records only `ACTOR_REPORTED`, and absent data is `UNKNOWN`. ForgeLoop
+never estimates tokens or accepts usage as verification evidence. The
+read-only `efficiency --task` command reports `NOT_COMPARABLE` until an
+optional project-local baseline has matching metadata.
+
+Execution-profile benchmark evidence is a separate observational boundary.
+The reproducible runner compares direct, balanced, and adaptive modes only
+when provider or host usage, actual timing, PASS verification, comparable
+steps, and matching metadata are present. Missing or non-comparable values
+remain `UNKNOWN`/`NOT_COMPARABLE`; no efficiency claim is inferred.
+
 ## CLI resolution policy
 
 Lifecycle-owned protocol state must be managed through the project-local ForgeLoop CLI:

package/README.md

@@ -195,6 +195,31 @@ configuration under `.forgeloop/`, and stores task-scoped protocol artifacts
 under `.forgeloop/task-state/<taskKey>/`.
 `update` preserves target-specific profile facts and locally modified files.
 
+ForgeLoop adapts protocol depth to task risk and scope, preserving verifiable
+completion while avoiding unnecessary context overhead for small tasks. The
+orthogonal `executionProfile` resolves to `light`, `balanced`, or `full`; it
+never weakens compliance policy, required verification, provenance, or
+validator-backed completion. Hosts can request bounded lifecycle context with
+`forgeloop next --task <id> --compact --json` and
+`forgeloop task-show --task <id> --compact --json`.
+
+Usage telemetry is optional and never estimated. `usage-record` keeps CLI data
+explicitly `ACTOR_REPORTED`; `efficiency --task` is read-only and compares only
+when a local baseline is metadata-compatible.
+
+Hosts can consume the read-only `task/context` integration resource for a
+profile-aware objective, guide, next-action, and verification projection. The
+profile changes presentation depth only; it never skips a required lifecycle
+phase or gate. Measured profile comparisons use the reproducible commands in
+[`docs/EXECUTION_PROFILE_BENCHMARKS.md`](./docs/EXECUTION_PROFILE_BENCHMARKS.md)
+and do not claim efficiency when provider or host telemetry is unavailable or
+non-comparable.
+
+The integration capability handshake marks the resolved profile as
+authoritative. Hosts without `task/context` use balanced compatibility behavior
+and must not invent a local LIGHT heuristic. Optional context usage is
+host-reported or `UNKNOWN`; values are never estimated.
+
 Before npm publication, the same source checkout can be exercised without a
 network or package lookup:
 

package/benchmarks/execution-profiles/README.md

@@ -0,0 +1,62 @@
+# Adaptive execution-profile benchmark scenarios
+
+These scenarios define the deterministic routing inputs used to compare direct
+execution, the historical balanced workflow, and the adaptive ForgeLoop
+workflow. They are scenario specifications, not provider measurements.
+
+Record provider or host usage only when it is actually reported. Keep unknown
+token, cache, cost, and timing values as `null`; ForgeLoop must not estimate
+them. A comparison is valid only when task/scenario, model, provider, prompt or
+spec fingerprint, project revision, benchmark version, and environment class
+match.
+
+The target profile is a guidance expectation. It does not change lifecycle
+phases, required gates, verification truth, authority boundaries, or validated
+completion.
+
+The required reference set includes the six original scenarios and
+`novatask-saas-landing-page.json`. NovaTask represents the original small SaaS
+landing-page workload: HTML5, CSS3, vanilla JavaScript, local static files,
+and no external services, auth, secrets, or publication. Its canonical
+`executionProfile.resolved` value is `light`.
+
+Record these dimensions independently when a real run is available: input and
+output tokens, cache reads and writes, total tokens, wall-clock time,
+verification status, verification cycles, comparable steps, visual quality,
+responsive quality, accessibility basics, interaction polish, and requirement
+completeness. Unavailable provider or reviewer measurements remain `null` or
+`NOT_AVAILABLE`; they are never inferred.
+
+Hosts may add optional `contextUsage` to a raw run with `HOST_REPORTED` values
+for task context, guides, history, protocol instructions, repository context,
+and other context. Use `UNKNOWN` with null items when unavailable. Complete
+light-versus-balanced context observations may report `CONTEXT_INFLATION`; the
+status is observational and never a lifecycle gate.
+
+For UI scenarios, an independent evaluator or blind human review may also
+report 0–5 scores for visual quality, responsive quality, accessibility,
+interaction polish, and requirements completeness. Missing scores remain null;
+implementer self-ratings are not an independent quality source.
+
+Initial non-blocking efficiency goals for LIGHT scenarios are P50 token
+overhead of at most +35% and P95 token overhead of at most +60% against a
+comparable direct baseline. These are benchmark objectives, not completion
+rules, and quality or verification coverage may not be traded for them.
+
+Raw runs may carry an optional `diagnostics` object with host-observed
+execution detail (model turns, tool calls, retries, correction cycles, files
+written, guide selections, termination reason, runaway-signal flags). Every
+field is nullable; never estimate a value the host does not actually report.
+
+Benchmark methodology v2 (`benchmarkVersion: "2"`) adds robust variability
+statistics (median, quartiles, IQR, MAD), per-comparison tail stability
+status, and deterministic token-outlier classification under the
+`TOKEN_IQR_1_5` policy. Runner repetitions are bounded by explicit tiers:
+`smoke` (1–3), `evidence` (5–10), and `tail` (20–30). Tail conclusions
+require at least 20 comparable pairs.
+
+Methodology versioning protects history: readers accept benchmark versions
+`1` and `2`, historical v1 run sets are never rewritten, and their stored
+aggregates reproduce byte-for-byte under the frozen v1 methodology. All of
+these diagnostics are observational and never change lifecycle truth,
+required gates, verification validity, or completion authority.

package/benchmarks/execution-profiles/api-feature.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "benchmarkVersion": "2",
+  "scenarioId": "api-feature",
+  "description": "Ordinary API behavior change without authentication or publication authority.",
+  "input": {
+    "workType": "api",
+    "surfaces": ["api", "data"],
+    "risks": [],
+    "platforms": ["server"]
+  },
+  "expectedProfile": "balanced",
+  "measurements": {
+    "direct": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopBalanced": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopAdaptive": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" }
+  }
+}

package/benchmarks/execution-profiles/authentication-change.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "benchmarkVersion": "2",
+  "scenarioId": "authentication-change",
+  "description": "Authentication behavior change crossing a trust boundary.",
+  "input": {
+    "workType": "api-auth",
+    "surfaces": ["auth", "api"],
+    "risks": [],
+    "platforms": ["server"]
+  },
+  "expectedProfile": "full",
+  "measurements": {
+    "direct": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopBalanced": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopAdaptive": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" }
+  }
+}

package/benchmarks/execution-profiles/documentation-correction.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "benchmarkVersion": "2",
+  "scenarioId": "documentation-correction",
+  "description": "Narrow documentation correction with no executable behavior or sensitive content.",
+  "input": {
+    "workType": "documentation",
+    "surfaces": [],
+    "risks": [],
+    "platforms": []
+  },
+  "expectedProfile": "light",
+  "measurements": {
+    "direct": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopBalanced": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopAdaptive": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" }
+  }
+}

package/benchmarks/execution-profiles/infrastructure-release.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 1,
+  "benchmarkVersion": "2",
+  "scenarioId": "infrastructure-release",
+  "description": "Infrastructure or release/publication work with external and potentially irreversible effects.",
+  "input": {
+    "workType": "release",
+    "surfaces": ["ci"],
+    "risks": ["publication"],
+    "platforms": ["ci"]
+  },
+  "expectedProfile": "full",
+  "measurements": {
+    "direct": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopBalanced": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopAdaptive": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" }
+  }
+}

package/benchmarks/execution-profiles/novatask-saas-landing-page.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "benchmarkVersion": "2",
+  "scenarioId": "novatask-saas-landing-page",
+  "description": "NovaTask reference workload: a local static SaaS landing page with no external or sensitive boundary.",
+  "input": {
+    "workType": "complete-website",
+    "surfaces": ["ui"],
+    "risks": [],
+    "platforms": ["web"],
+    "behaviorChange": false,
+    "executableChange": false
+  },
+  "expectedProfile": "light",
+  "referenceTask": {
+    "name": "NovaTask static SaaS landing page",
+    "requirements": [
+      "HTML5",
+      "CSS3",
+      "vanilla JavaScript",
+      "local static files"
+    ],
+    "exclusions": [
+      "external services",
+      "authentication",
+      "secrets",
+      "publication"
+    ],
+    "artifactMode": "local-static-files"
+  },
+  "measurements": {
+    "direct": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopBalanced": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" },
+    "forgeloopAdaptive": { "inputTokens": null, "outputTokens": null, "cacheReadTokens": null, "cacheWriteTokens": null, "totalTokens": null, "wallClockMs": null, "verification": "NOT_AVAILABLE" }
+  }
+}