@cassiomc1/forgeloop 1.9.0 → 1.10.0

package/AGENT_COMPATIBILITY.md

@@ -9,3 +9,18 @@ ForgeLoop is vendor-neutral and does not use a supported-agent allowlist.
 The canonical integration contract is:
 
 [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+
+## Current harness expectations
+
+These expectations apply to any compatible harness even though this filename is
+retained as a deprecated compatibility stub:
+
+- Feature-detect capability versions from `protocol-info --json` or the stable
+  Integration API; do not infer support from a package version.
+- Do not auto-recall advisory context, execute advisory text, or treat it as
+  state, evidence, authority, completion, or next-action truth.
+- Do not infer handoff acceptance from receiving a file or message. Run
+  `handoff-accept` only when the receiving harness actually consumes the
+  immutable handoff.
+- Preserve the distinction between `consumerId`, harness labels, and
+  authenticated identity; none grants authority or transfers claims.

package/DELEGATION_PROTOCOL.md

@@ -70,6 +70,12 @@ Valid statuses are `complete`, `complete-with-concerns`, `needs-context`, and
 Complete results also require structured observed or inferred verification
 evidence.
 
+Canonical handoff acceptance is not delegation acceptance. A handoff envelope
+and its `HANDOFF_ACCEPTED` operational receipt do not create a delegated task,
+approve a brief, transfer claims, or establish reviewer authority. Delegation
+authority remains in this canonical delegation contract and its validated task
+brief/result relationships.
+
 ## Review and integration
 
 An independent reviewer receives the approved brief, resulting diff,

package/DOCS_INDEX.md

@@ -15,7 +15,7 @@ integration and guide context. Use this map before editing documentation.
 | Need | Canonical source | Boundary |
 | --- | --- | --- |
 | Getting started tutorial | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough from init to completion |
-| Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
+| Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational resume guidance, immutable handoffs, and multi-tool resumption |
 | Agent bootstrap summary | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) | Generated concise navigation aid for protocol invariants and commands |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
@@ -25,11 +25,13 @@ integration and guide context. Use this map before editing documentation.
 | Structural quality feedback | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) | Provider-neutral baseline, delta policy, Sentrux boundary, lifecycle integration, and troubleshooting |
 | Diagnostic model | [`docs/DIAGNOSTIC_MODEL.md`](./docs/DIAGNOSTIC_MODEL.md) | Structured diagnostic cases, interventions, hypothesis dispositions, information gain |
 | Execution trace and observability | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) | `history`, `trace`, `reflect`, and task-level `inspect` read-only projections |
-| Workspace, handoff, responsibility, and scope | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) and [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Optional task boundaries and deterministic verification planning |
+| Workspace, handoff, responsibility, and scope | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) and [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Optional task boundaries, immutable handoffs, and deterministic verification planning |
+| Handoff acceptance | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Ledger-backed operational receipt; no claim transfer, evidence, or authority |
 | Code attestation and revision coverage | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) | Source-content manifests, in-toto statements, signatures, and range verification |
 | Revision and signing providers | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md) and [`docs/SIGNING_PROVIDERS.md`](./docs/SIGNING_PROVIDERS.md) | Provider-neutral extension contracts |
 | 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 |
+| Advisory context providers | [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) | Optional external host context, non-evidence trust boundary, allowlist normalization, and safety rules |
 | 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 |
 | Knowledge integration gap analysis | [`docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md`](./docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md) | Repository-only research audit of candidate coverage, proven gaps, canonical homes, context cost, and intentional skip/defer decisions |

package/LOOP_ENGINEERING.md

@@ -1376,6 +1376,15 @@ completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
 installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
+Canonical handoff acceptance is orthogonal to lifecycle phase transitions. The
+`HANDOFF_ACCEPTED` event is an exactly-once, ledger-backed operational receipt;
+it does not add a lifecycle phase, transfer claims, create evidence, authorize
+work, or approve review. A receiving harness runs `handoff-accept` only when it
+actually consumes the immutable handoff. Advisory context is also outside the
+canonical lifecycle: providers are lazy and opt-in through the Integration API,
+and their output cannot determine state, evidence, authority, completion, or
+the next action.
+
 ## Optional task boundaries and code attestation
 
 ForgeLoop keeps the following extensions optional so existing task artifacts
@@ -1399,6 +1408,10 @@ review evidence, or prove completion. An optional actor note or recipient hint
 is descriptive metadata only. This envelope is distinct from mutable
 `continuity.json`, which is operational resume context and non-evidence.
 
+`handoff-accept` records the receiver's operational consumption only. It does
+not make `consumerId`, `harness`, a recipient hint, or a handoff envelope an
+authenticated identity, delegation approval, or lifecycle authority.
+
 <a id="FL-SCOPE-001"></a> **FL-SCOPE-001 — A verification scope MUST narrow execution only from**
 current canonical changed paths, effective claims, or an explicit full-project
 requirement. The resolver never guesses impacted tests, and a stale scope is

package/LOOP_SYSTEM_DESIGN.md

@@ -465,6 +465,39 @@ The README explains the file set, activation behavior, current/relative/absolute
 target installation, first-run profile flow, local validation commands, and safe
 update practice.
 
+## Advisory and handoff trust boundaries
+
+Optional advisory context remains outside canonical lifecycle state and evidence:
+
+```text
+External advisory provider
+        |
+        v
+bounded recall input
+        |
+        v
+allowlist normalization
+        |
+        v
+ADVISORY / NON_EVIDENCE / NON_EXECUTABLE
+```
+
+Handoff acceptance is a separate operational receipt over an immutable snapshot:
+
+```text
+canonical state + current repository
+        |
+        v
+immutable handoff
+        |
+        v
+HANDOFF_ACCEPTED ledger receipt
+```
+
+Neither boundary transfers claims or creates evidence or authority. Advisory
+providers are lazy and opt-in through the Integration API; handoff acceptance
+is orthogonal to lifecycle phases and does not authorize the receiving harness.
+
 ## Out of scope
 
 - remote prompt services or databases;

package/ORCHESTRATOR_INTEGRATION.md

@@ -159,6 +159,15 @@ claims, lifecycle transitions, evidence binding, completion, and fail-closed
 trust decisions. Workspace binding, responsibility, narrow verification,
 signing, and MCP are not prerequisites for basic protocol compatibility.
 
+Handoff acceptance is orthogonal to the lifecycle transition graph. An
+orchestrator may call `handoff-accept` only after the receiving harness has
+actually consumed the immutable snapshot. The resulting `HANDOFF_ACCEPTED`
+event is an exactly-once operational receipt; it does not accept delegation,
+transfer claims, create evidence, authenticate `consumerId` or `harness`, or
+grant lifecycle or review authority. Advisory context is likewise optional,
+lazy, and Integration-API-only; it must not be loaded automatically or used as
+an executable instruction source.
+
 Focused visual fallbacks are maintained in the [Verification Trust
 Flow](./docs/REVISION_PROVIDERS.md#differential-verification-scope) and [Code
 Attestation Chain](./docs/CODE_ATTESTATION.md#completion-flow).

package/PROTOCOL_INTEGRATION.md

@@ -181,6 +181,37 @@ authority, provenance, and safety-floor decisions remain unchanged.
 validator-backed completion remains unchanged.
 ```
 
+## Capability negotiation
+
+The public capability handshake exposes additive capability families separately
+from Protocol v1, schema v1, and Integration API v1:
+
+| Capability family | Version | Boundary |
+| --- | --- | --- |
+| `canonicalHandoffs` | v2 | Immutable handoff snapshots with ledger-backed exactly-once operational acceptance |
+| `advisoryContextProviders` | v1 | Lazy, opt-in, provider-neutral Integration API injection only |
+
+`canonicalHandoffs` v2 advertises `supported: true`, immutable snapshots,
+`lifecycleAuthority: false`, `evidenceAuthority: false`,
+`exactlyOnceAcceptance: true`, `acceptanceLedgerBacked: true`, and the
+`handoff-accept` command with `OPEN`, `ACCEPTED`, `UNBOUND`, and `INCONSISTENT`
+status projections. Acceptance is an operational receipt only: it does not
+transfer claims or create evidence or authority, and it is orthogonal to phase
+transitions.
+
+`advisoryContextProviders` v1 is `integrationApiOnly: true`, lazy, and opt-in.
+Its results are never persisted by ForgeLoop and are never canonical state,
+evidence, authority, completion truth, next-action authority, or executable
+instructions. `protocol-info` may advertise the capability, but advisory
+recall remains a programmatic Integration API operation; there is no stock
+`context-recall` CLI command.
+
+A consumer that understands `canonicalHandoffs` v1 but not v2 may disable the
+handoff-specific UI while keeping Protocol v1 core functionality available.
+Consumers must feature-detect the capability family and must not mark the
+whole project incompatible merely because an optional capability version is
+newer.
+
 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,

package/README.md

@@ -31,6 +31,7 @@ relevant guides.
 - **Inspect a real ForgeLoop execution** → [`poc/README.md`](./poc/README.md)
 - **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
+- **Optional advisory context providers** → [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md)
 - **Agent bootstrap summary** → [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md)
 - **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **CLI command reference** → [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
@@ -135,6 +136,14 @@ informational or completion-required. Sentrux is an optional user-managed
 sensor, not a ForgeLoop dependency or a universal software-quality score. See
 [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md).
 
+### Optional advisory context
+
+ForgeLoop can consume host-provided advisory context through the Integration
+API. Providers are lazy and opt-in, and ForgeLoop does not persist their
+results. Provider output is never lifecycle state, evidence, authority,
+completion truth, or next-action authority, and it is never executable as a
+protocol command. See [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md).
+
 ### Optional task boundaries and differential verification
 
 Workspace binding, immutable handoff envelopes, and responsibility contracts
@@ -231,6 +240,10 @@ 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.
 
+`protocol-info --json` advertises the optional `advisoryContextProviders` v1
+capability, but advisory recall remains Integration API only. The stock CLI
+does not auto-recall providers and does not expose a `context-recall` command.
+
 Before npm publication, the same source checkout can be exercised without a
 network or package lookup:
 
@@ -303,6 +316,33 @@ forgeloop reconcile-continuity --task example-task --json
 forgeloop next --task example-task --json
 ```
 
+For an explicit immutable handoff, use the complete operational flow:
+
+```bash
+forgeloop handoff-create --task example-task --recipient codex --json
+forgeloop handoff-list --task example-task --json
+forgeloop handoff-show --task example-task --id <handoff-id> --json
+forgeloop handoff-accept \
+  --task example-task \
+  --handoff <handoff-id> \
+  --consumer-id codex-session-42 \
+  --harness codex \
+  --json
+```
+
+Handoff projections use these statuses:
+
+```text
+OPEN         valid bound snapshot awaiting operational acceptance
+ACCEPTED     exactly-once operational receipt recorded
+UNBOUND      legacy handoff without exact work-state binding
+INCONSISTENT ledger, digest, or acceptance history is not trustworthy
+```
+
+Acceptance is `OPERATIONAL_RECEIPT_ONLY`: it transfers no claims and creates
+no evidence or authority. Same-consumer retries are idempotent; a different
+consumer receives a fail-closed `E_HANDOFF_ALREADY_ACCEPTED` result.
+
 See [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) for full handoff and recovery procedures.
 
 ### Multi-task concurrent project state

package/TERMINOLOGY.md

@@ -47,6 +47,18 @@
 | Attestation statement | A deterministic in-toto Statement v1 binding the code manifest to valid ForgeLoop completion evidence. |
 | Revision-range coverage | A post-completion result asking whether changed paths between two revisions are covered by valid task attestations. |
 | Generic CI | The provider-neutral range-verification boundary that thin platform adapters may invoke without adding platform trust rules to the core. |
+| Advisory Context | Optional host-provided information returned for human or agent consideration; it is not canonical task state, evidence, authority, completion truth, or next-action authority. |
+| Advisory Context Provider | A runtime-injected Integration API provider with a declared identity and bounded recall method; providers are lazy, opt-in, and not persisted by ForgeLoop. |
+| Portable Context | Bounded text normalized for transport, with control characters, secrets, unsafe paths, and unsupported fields rejected or discarded according to the canonical boundary. |
+| Handoff Acceptance | An exactly-once, ledger-backed operational receipt that records consumption of an immutable handoff without transferring claims or creating evidence or authority. |
+| Consumer ID | A caller-supplied descriptive key used to make handoff acceptance idempotent; it is not an authenticated identity. |
+| Acceptance Status | The derived handoff projection `OPEN`, `ACCEPTED`, `UNBOUND`, or `INCONSISTENT`; it is not a lifecycle phase. |
+| Continuity Lint | Non-authoritative, non-evidence diagnostics for stale or contradictory operational resume hints. |
+
+`consumerId` is not an authenticated identity. A `harness`, recipient hint,
+session label, or transport channel is descriptive metadata, not authority.
+The harness owns execution and presentation; ForgeLoop owns canonical state,
+evidence relationships, and validated lifecycle decisions.
 
 | Execution continuity | Bounded current-task implementation context used to resume the same ForgeLoop task across sessions or harnesses. |
 | Continuity artifact | `.forgeloop/continuity.json`; non-evidence operational context bound to canonical work state. |

package/THREAT_MODEL.md

@@ -124,6 +124,30 @@ provide a universal exactly-once guarantee.
 | Signature confusion | A plain digest or platform publication signal is presented as a cryptographic signature | External signing-provider boundary | `ATTESTED` requires a valid external signature under the requested signer policy; private keys and tokens never enter persisted artifacts | Trust in the external signer and transparency infrastructure remains outside ForgeLoop | `tests/signing-provider.test.js` |
 | Incomplete revision coverage | A changed source path has no valid task attestation or overlaps another task with a conflicting digest | Provider-neutral range coverage evaluator | Changed, covered, uncovered, and overlapping paths are computed from the selected revision provider; enforcement fails closed on gaps or conflicts | Coverage is limited to the provider's observable revision/content boundary | `tests/attestation-coverage.test.js`, `tests/generic-ci-attestation.test.js` |
 
+## Advisory context provider boundary
+
+Advisory provider output is untrusted external input. ForgeLoop exposes only a
+bounded, allowlisted, non-evidence and non-executable projection through the
+Integration API. Provider identity and availability are explicit; no provider
+is discovered or invoked by lifecycle commands, and provider text is never
+treated as trusted protocol input.
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Prompt injection in advisory results | Portable text checks, authority-field stripping, and `actionability: NON_EXECUTABLE` prevent provider text from becoming commands or lifecycle instructions | A host may still choose to display or act on advisory text outside ForgeLoop | `tests/advisory-context-security.test.js`, `tests/portable-context.test.js` |
+| Sensitive provider-output leakage | Secret-like values are rejected in selected portable fields; unknown fields are discarded before logging or projection | Unknown encodings and secrets returned only through an external host remain outside this scanner | `tests/advisory-context-security.test.js` |
+| Provider identity substitution | Registry key and resolved provider `id` must match the declared identity | A host that controls the runtime registry can replace its own provider before the call | `tests/advisory-context-runtime.test.js` |
+| Unbounded provider retrieval | Query, item, total-output, raw-result, and timeout budgets are normalized and enforced before/while provider execution | The host controls provider resource usage outside the bounded call | `tests/advisory-context-service.test.js`, `tests/advisory-context-provider.test.js` |
+| Historical command replay from advisory text | Advisory output cannot satisfy command input, evidence, state, or next-action authority; recall is never automatic | A receiving host must still avoid copying untrusted text into its own command runner | `tests/advisory-context-security.test.js` |
+| Handoff acceptance replay | Acceptance is keyed by the immutable handoff and consumer identity and is checked against the append-only ledger | External systems may still deliver duplicate messages; callers must surface the canonical rejection | `tests/handoff-acceptance.test.js` |
+| Handoff double-consumption race | Serialized ledger append and exactly-once acceptance projection permit one consumer; same-consumer retry is idempotent | Filesystem privilege outside ForgeLoop can still corrupt local artifacts | `tests/handoff-acceptance.test.js`, `tests/concurrent-ledger.test.js` |
+| Stale Git checkout acceptance | Acceptance compares the handoff snapshot with the current branch and HEAD, work-state, contract, route, and changed paths | A separately privileged process can change the checkout immediately after validation | `tests/handoff-acceptance.test.js` |
+| Stale contract/route handoff | Handoff creation and acceptance bind contract and route fingerprints and fail closed on drift | The caller must create a fresh handoff after a legitimate contract or route change | `tests/handoff-envelope.test.js`, `tests/handoff-acceptance.test.js` |
+| Invalid ledger projection | Handoff readers validate digest, event relationships, and the complete ledger; invalid history projects `INCONSISTENT`, never `OPEN` or `ACCEPTED` | Local consistency validation is not remote attestation against a privileged rewrite | `tests/handoff-acceptance.test.js`, `tests/handoff-tamper.test.js` |
+
+ForgeLoop does not make advisory text trusted. It makes the boundary explicit,
+bounded, and fail-closed where protocol-owned interpretation is required.
+
 ## Structural-quality provider boundary
 
 Structural-quality observations are untrusted external data. The built-in

package/completions/_forgeloop

@@ -1,7 +1,7 @@
 #compdef forgeloop
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
 _arguments \
-  '1:command:(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 quality-baseline quality-status quality-verify 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)' \
+  '1:command:(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-accept 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 quality-baseline quality-status quality-verify 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)' \
   '*::options:->options'
 case $words[2] in
   action-authorize) _arguments '--action[durable action ID]' '--approval[current fingerprint-bound approval]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -28,6 +28,7 @@ case $words[2] in
   doctor) _arguments '--adopt[preserve an existing adapter in the manifest]' '--fix[restore missing managed template files]' '--help[show this help]' '--json[emit doctor findings as JSON]' '--path[target project directory (default: current directory)]' '--strict[treat warnings as unhealthy]' '--version[show the installed package version]' ;;
   efficiency) _arguments '--baseline[optional comparable efficiency baseline JSON]' '--help[show this help]' '--json[emit efficiency metrics as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   eval) _arguments '--help[show this help]' '--json[emit evaluation as JSON]' '--path[target project directory (default: current directory)]' '--scenario[project-local trajectory scenario JSON]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
+  handoff-accept) _arguments '--consumer-id[consumer identifier accepting the handoff]' '--handoff[handoff identifier]' '--harness[optional harness accepting the handoff]' '--help[show this help]' '--json[emit acceptance result as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-create) _arguments '--help[show this help]' '--json[emit handoff as JSON]' '--note[non-authoritative handoff note]' '--path[target project directory (default: current directory)]' '--recipient[non-authoritative recipient hint]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-list) _arguments '--help[show this help]' '--json[emit handoff list as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-show) _arguments '--help[show this help]' '--id[handoff identifier]' '--json[emit handoff as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;

package/completions/forgeloop.bash

@@ -30,6 +30,7 @@ _forgeloop() {
       doctor) command="doctor" ;;
       efficiency) command="efficiency" ;;
       eval) command="eval" ;;
+      handoff-accept) command="handoff-accept" ;;
       handoff-create) command="handoff-create" ;;
       handoff-list) command="handoff-list" ;;
       handoff-show) command="handoff-show" ;;
@@ -91,7 +92,7 @@ _forgeloop() {
     esac
   done
   if [[ -z "\${command}" && "\${cur}" != -* ]]; then
-    COMPREPLY=( $(compgen -W '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 quality-baseline quality-status quality-verify 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' -- "$cur") )
+    COMPREPLY=( $(compgen -W '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-accept 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 quality-baseline quality-status quality-verify 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' -- "$cur") )
     return
   fi
   case "\${command}" in
@@ -119,6 +120,7 @@ _forgeloop() {
     doctor) COMPREPLY=( $(compgen -W '--adopt --fix --help --json --path --strict --version' -- "$cur") );;
     efficiency) COMPREPLY=( $(compgen -W '--baseline --help --json --path --task --version' -- "$cur") );;
     eval) COMPREPLY=( $(compgen -W '--help --json --path --scenario --task --version' -- "$cur") );;
+    handoff-accept) COMPREPLY=( $(compgen -W '--consumer-id --handoff --harness --help --json --path --task --version' -- "$cur") );;
     handoff-create) COMPREPLY=( $(compgen -W '--help --json --note --path --recipient --task --version' -- "$cur") );;
     handoff-list) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     handoff-show) COMPREPLY=( $(compgen -W '--help --id --json --path --task --version' -- "$cur") );;

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 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 quality-baseline quality-status quality-verify 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_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-accept 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 quality-baseline quality-status quality-verify 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'
@@ -173,6 +173,14 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'path' -d 'tar
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'scenario' -d 'project-local trajectory scenario JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -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 eval' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'consumer-id' -d 'consumer identifier accepting the handoff'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'handoff' -d 'handoff identifier'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'harness' -d 'optional harness accepting the handoff'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'json' -d 'emit acceptance result as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -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 handoff-accept' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'json' -d 'emit handoff as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'note' -d 'non-authoritative handoff note'

package/docs/ADVISORY_CONTEXT.md

@@ -0,0 +1,174 @@
+# Advisory Context & External Provider Boundary
+
+## Overview
+
+ForgeLoop treats external advisory context as **optional, host-injected, lazy,
+and strictly advisory**.
+
+The core invariant of the protocol is:
+
+```
+MEMORY != STATE
+MEMORY != EVIDENCE
+MEMORY != AUTHORITY
+MEMORY != COMPLETION
+MEMORY != NEXT ACTION
+```
+
+ForgeLoop contains **no built-in vector database, SQLite engine, or full-text search (FTS)** dependencies. Memory systems belong to hosts, IDEs, orchestrators, and harnesses. ForgeLoop provides the hardened runtime contract, trust boundary, portable text sanitization, and allowlist normalization.
+
+## Architectural Boundaries
+
+1. **Non-Authoritative (`ADVISORY`)**: Advisory memory can provide context or suggestions to an agent, but cannot dictate lifecycle state, phase transitions, or next actions.
+2. **Non-Evidence (`evidenceAuthority: "NONE"`)**: Stored memories or suggestions cannot satisfy verification requirements, pass gates, or serve as execution receipts.
+3. **Non-Executable (`actionability: "NON_EXECUTABLE"`)**: Output items cannot be executed directly as protocol commands.
+4. **Ephemeral & Unpersisted (`persisted: false`)**: ForgeLoop never persists external recall results to `.forgeloop/` state or the event ledger.
+5. **Lazy Provider Evaluation**: ForgeLoop runtime commands (`next`, `status`, `preflight`, `complete`, `task-show`, etc.) never invoke advisory memory providers. Recall occurs only when a host explicitly invokes the integration recall service.
+
+## Registering Providers
+
+Hosts configure providers through the runtime context:
+
+```javascript
+import { createForgeLoopContext } from "@cassiomc1/forgeloop/integration";
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "my-memory": {
+      id: "my-memory",
+      version: "1.0.0",
+      async recall({ projectPath, taskId, query, limit, maxItemChars, maxTotalChars, timeoutMs }) {
+        // Query host vector database, knowledge base, or memory cache
+        return {
+          items: [
+            {
+              title: "Previous Architecture Decision",
+              summary: "Decided to use rotating refresh tokens with 15-minute expiry.",
+              sourceRef: "docs/decisions/auth-tokens.md",
+              confidence: 0.95,
+            },
+          ],
+        };
+      },
+    },
+  },
+});
+```
+
+Provider IDs must match `^[a-z0-9][a-z0-9_-]*$`. Providers may be plain objects or async factory functions. The registry key and the resolved provider `id` must match exactly; a factory that resolves to another identity fails with `E_ADVISORY_CONTEXT_PROVIDER_INVALID` before `recall` is called.
+
+## Querying Advisory Context
+
+Hosts explicitly invoke `recallAdvisoryContext`:
+
+```javascript
+import { recallAdvisoryContext } from "@cassiomc1/forgeloop/integration";
+
+const result = await recallAdvisoryContext({
+  target: "/path/to/project",
+  taskId: "auth-impl-42",
+  providerName: "my-memory",
+  query: "token refresh strategy",
+  limit: 5,
+  runtimeContext,
+});
+```
+
+### Result Schema
+
+Every returned result is normalized, frozen, and stamped with immutable trust metadata:
+
+```json
+{
+  "provider": {
+    "id": "my-memory",
+    "version": "1.0.0"
+  },
+  "taskId": "auth-impl-42",
+  "authority": "ADVISORY",
+  "evidenceAuthority": "NONE",
+  "actionability": "NON_EXECUTABLE",
+  "trustRole": "NON_EVIDENCE_ADVISORY_CONTEXT",
+  "persisted": false,
+  "items": [
+    {
+      "title": "Previous Architecture Decision",
+      "summary": "Decided to use rotating refresh tokens with 15-minute expiry.",
+      "sourceRef": "docs/decisions/auth-tokens.md",
+      "confidence": 0.95,
+      "itemFingerprint": "4a7d...3b1f"
+    }
+  ]
+}
+```
+
+## Normalization & Authority Stripping
+
+ForgeLoop checks the raw result shape and item count, then selects bounded items and projects only allowlisted fields before portable safety inspection. Unknown raw fields—including secret-like or cyclic metadata—are discarded and are never copied or logged. A secret in a selected field still fails closed.
+
+Any raw fields returned by a provider that attempt to assert protocol authority are completely stripped during normalization:
+
+- `nextAction`, `command`, `phase`
+- `evidence`, `approval`, `authority`
+- `writeClaims`, `changedPaths`, `checkIds`
+
+Only allowlisted fields (`title`, `summary`, `sourceRef`, `observedAt`, `confidence`) survive. Each item receives a deterministic SHA-256 `itemFingerprint`.
+
+## Portable Safety Boundary
+
+All text flowing into or out of advisory recall is verified:
+
+- **Control Character Rejection**: ASCII control characters (`\x00-\x08`, `\x0B-\x0C`, `\x0E-\x1F`, `\x7F`) throw `E_PORTABLE_CONTEXT_INVALID`.
+- **Secret Scanning**: Inputs and outputs containing secret tokens (e.g., `Bearer <token>`, `ghp_`, AWS keys, private keys) throw `E_PORTABLE_CONTEXT_INVALID`.
+- **Budget Enforcements**:
+
+  - Max query characters: 1,000 chars (`E_ADVISORY_CONTEXT_QUERY_INVALID`)
+  - Max item summary: 4,000 chars (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Default item limit: 6 items (max 20)
+  - Default total characters: 6,000 chars (max 16,000) (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Raw provider result ceiling: 100 items (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Default timeout: 5,000 ms, max 30,000 ms (`E_ADVISORY_CONTEXT_TIMEOUT`)
+
+ForgeLoop normalizes recall limits before provider dispatch. Valid oversized
+integer requests are clamped to the canonical maxima, and non-finite,
+non-integer, below-minimum, string, boolean, object, or null values fail before
+provider lookup with `E_ADVISORY_CONTEXT_REQUEST_INVALID`. Providers therefore
+never receive caller-requested budgets above ForgeLoop's supported maxima.
+
+## Replay safety and failure handling
+
+Advisory recall is an explicit host operation. ForgeLoop does not record a
+provider query, provider response, or item fingerprint in the task event ledger,
+and a later recall is never treated as proof that an earlier response was
+current. Hosts should re-query when context is needed and must independently
+validate any proposed action or lifecycle step against canonical state.
+
+Provider failures remain advisory failures and do not block the canonical loop.
+The public boundary reports these stable codes:
+
+| Code | Meaning |
+| --- | --- |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` | Provider identity or recall contract is invalid. |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | The requested provider is not registered in the runtime context. |
+| `E_ADVISORY_CONTEXT_QUERY_INVALID` | The query is empty, unsafe, or exceeds the query budget. |
+| `E_ADVISORY_CONTEXT_REQUEST_INVALID` | A recall budget has an invalid type, range, or numeric value. |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | The provider returned an invalid result shape. |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Provider recall exceeded the bounded timeout. |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | The raw or normalized provider output exceeded a bounded limit. |
+| `E_PORTABLE_CONTEXT_INVALID` | Portable text contains unsafe controls, secrets, or unsupported content. |
+
+## What ForgeLoop Never Does Automatically
+
+- It does not look up a provider on startup.
+- It does not look up a provider for `status`, `next`, `preflight`, `complete`,
+  `task-show`, or the read-only `task/context` resource.
+- It does not persist provider results, queries, or provider metadata in
+  `.forgeloop/` or the event ledger.
+- It does not turn provider text into a command, lifecycle transition, check,
+  evidence record, approval, claim, or next action.
+- It does not infer provider trust from a package version, a source path, or a
+  host label. The provider identity contract is resolved at the Integration
+  API boundary and remains descriptive rather than authenticated authority.
+
+The host owns whether and when to display or use advisory context. ForgeLoop
+owns only the bounded normalization and trust-role projection.

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.9.0
+Package version: 1.10.0
 
 ## Canonical loop
 
@@ -74,7 +74,8 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | Feature | Version | Supported |
 | --- | --- | --- |
 | adaptiveExecutionProfiles | 1 | yes |
-| canonicalHandoffs | 1 | yes |
+| advisoryContextProviders | 1 | yes |
+| canonicalHandoffs | 2 | yes |
 | capabilityPolicy | 1 | yes |
 | codeAttestation | 1 | yes |
 | compactLifecycleOutput | 1 | yes |
@@ -100,6 +101,21 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | verificationExecutionIsolation | 1 | yes |
 | workspaceBinding | 1 | yes |
 
+## Capability contracts
+
+- `canonicalHandoffs` v2: immutable, supported, and
+  ledger-backed for exactly-once operational acceptance through
+  `handoff-accept`. Acceptance statuses are
+  `OPEN` / `ACCEPTED` / `UNBOUND` / `INCONSISTENT`; it creates no claims,
+  evidence, or lifecycle authority.
+- `advisoryContextProviders` v1: provider-neutral,
+  Integration-API-only, lazy, and opt-in. Provider results are not persisted by
+  ForgeLoop and are never lifecycle state, evidence, authority, or executable
+  instructions.
+
+Protocol v1, schema v1, and Integration API v1 remain independent of these
+capability-family versions.
+
 ## Public artifact registry
 
 | Key | Scope | Path | Schema | Trust role |
@@ -248,6 +264,12 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | responsibility-set | MUTATING | Creates immutable, mechanically verifiable constraints for a task pass. |
 | responsibility-status | READ_ONLY | Validates active responsibility constraints against current paths, inputs, and checks. |
 
+### task
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| handoff-accept | MUTATING | Accepts an immutable handoff exactly once in the task event ledger. |
+
 ### verification
 
 | Command | Mutation | Purpose |
@@ -301,8 +323,12 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | E_ATTESTATION_TARGET_REF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_ATTESTATION_UNSIGNED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_CLI_INVOCATION_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_ACCEPTANCE_INCONSISTENT | Handoff acceptance disagrees with task event ledger history. |
+| E_HANDOFF_ACCEPTANCE_UNBOUND | Handoff snapshot lacks required workStateFingerprint binding. |
+| E_HANDOFF_ALREADY_ACCEPTED | Handoff was already accepted by a different consumer. |
 | E_HANDOFF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_HANDOFF_NOT_FOUND | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_STALE | Handoff snapshot has drifted from the current canonical task state or repository. |
 | E_HANDOFF_STATE_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_HANDOFF_TAMPERED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_RESPONSIBILITY_FROZEN_INPUT_DRIFT | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |