@cassiomc1/forgeloop 1.9.0 → 1.10.0

package/docs/ARTIFACT_REFERENCE.md

@@ -950,6 +950,7 @@ completion, or authority evidence.
   - `phase` *(string, required, minLength: 1)*
   - `revision` *(integer, required, minimum: 0)*
   - `verificationCycle` *(integer, required, minimum: 1)*
+  - `workStateFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
   - `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
   - `routeFingerprint` *(string or null, required)*
   - `repositoryFingerprint` *(object, required)*
@@ -965,6 +966,19 @@ completion, or authority evidence.
 
 <!-- END FORGELOOP GENERATED: schema:handoff-envelope -->
 
+The handoff `state` binds the immutable snapshot to the exact
+`workStateFingerprint`, contract identity, route identity, selected-guide
+context, repository branch/HEAD fingerprint, changed paths, and historical
+write claims observed at creation. `HANDOFF_CREATED` records the envelope's
+relationship to the task ledger. A later `HANDOFF_ACCEPTED` event records only
+that one consumer operationally consumed the unchanged snapshot; it does not
+transfer claims, create evidence, or grant authority.
+
+Acceptance status is a derived projection from the immutable handoff, its
+digest, and the validated event ledger. Acceptance fields are intentionally not
+stored in the handoff JSON itself. Invalid or mismatched ledger history
+projects `INCONSISTENT`, never a successful acceptance.
+
 ### 2.27 `task-state/<taskKey>/responsibility.json`
 
 <!-- forgeloop-doc: schema=responsibility artifact=.forgeloop/task-state/<task-key>/responsibility.json -->

package/docs/CLI_REFERENCE.md

@@ -66,6 +66,7 @@ error codes. Default output and default JSON remain unchanged.
 | **Durable Actions & Approvals** | [`run-action`](#run-action), [`action-propose`](#action-propose), [`action-record`](#action-record), [`action-show`](#action-show), [`action-reconcile`](#action-reconcile), [`action-verify`](#action-verify), [`action-authorize`](#action-authorize), [`approval-request`](#approval-request), [`approval-resolve`](#approval-resolve) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
 | **workspace** | [`workspace-bind`](#workspace-bind), [`workspace-status`](#workspace-status) |
+| **task** | [`handoff-accept`](#handoff-accept) |
 | **scope** | [`responsibility-set`](#responsibility-set), [`responsibility-status`](#responsibility-status) |
 | **attestation** | [`attestation-create`](#attestation-create), [`attestation-verify`](#attestation-verify), [`attestation-status`](#attestation-status), [`attestation-verify-range`](#attestation-verify-range) |
 
@@ -157,6 +158,9 @@ Lists immutable handoff snapshots for a task.
 
 - **Purpose**: Inspect existing handoff snapshots without changing them.
 - **Mutation**: Read-only.
+- **Acceptance projection**: Derives `OPEN`, `ACCEPTED`, `UNBOUND`, or
+  `INCONSISTENT` from the validated event ledger. Invalid or unreadable ledgers
+  are fail-closed and expose `reasonCodes`; they are never treated as empty.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:handoff-list:options -->
@@ -178,6 +182,8 @@ Lists immutable handoff snapshots for a task.
 Reads and verifies one immutable handoff snapshot.
 
 - **Purpose**: Inspect one handoff by ID and validate its digest and bindings.
+- **Acceptance projection**: Uses the same fail-closed ledger-derived status as
+  `handoff-list`.
 - **Mutation**: Read-only.
 - **Options**:
 
@@ -196,6 +202,37 @@ Reads and verifies one immutable handoff snapshot.
   forgeloop handoff-show --task task-001 --id handoff-001 --json
   ```
 
+### `handoff-accept`
+
+Records exactly-once acceptance of an immutable handoff into the task event ledger.
+
+- **Purpose**: Bind an incoming consumer/harness to an immutable handoff snapshot.
+- **Mutation**: Appends a `HANDOFF_ACCEPTED` event.
+- **Freshness**: Acceptance requires the current canonical state and directly
+  observed repository branch/HEAD to match the immutable snapshot, including a
+  clean committed HEAD drift check.
+- **Human output**: Reports `authority: OPERATIONAL_RECEIPT_ONLY`,
+  `evidence: NONE`, and `claims transferred: NO`; acceptance is exactly-once
+  operational receipt only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:handoff-accept:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--handoff <id>`: handoff identifier
+- `--consumer-id <id>`: consumer identifier accepting the handoff
+- `--harness <name>`: optional harness accepting the handoff
+- `--json`: emit acceptance result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:handoff-accept:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop handoff-accept --task task-001 --handoff handoff-001 --consumer-id agent-42 --json
+  ```
+
 ### `responsibility-set`
 
 Creates immutable constraints for the current task pass.
@@ -914,6 +951,9 @@ Records operational handoff context before pausing or switching tools.
 Reconciles continuity with the active work state and checkout.
 
 - **Purpose**: Compares continuity bindings against the canonical work state, contract, phase, repository fingerprint, and checkout state.
+- **Lint**: Returns deterministic `PASS`/`WARN` findings for stale completed
+  item references, role conflicts, missing `inspectFirst` paths, and empty hint
+  sets without changing reconciliation classification.
 - **When to use**: When starting a session in an active task.
 - **Mutation**: Read-only.
 - **Options**:

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -114,6 +114,33 @@ exists, compare the current checkout, and only then follow `forgeloop next`.
 Handoff notes can focus inspection, but only valid execution evidence,
 completion receipts, and the append-only ledger can satisfy verification.
 
+The complete immutable-handoff flow is:
+
+```bash
+forgeloop handoff-create --task auth-feature --recipient codex --json
+forgeloop handoff-list --task auth-feature --json
+forgeloop handoff-show --task auth-feature --id <handoff-id> --json
+forgeloop handoff-accept \
+  --task auth-feature \
+  --handoff <handoff-id> \
+  --consumer-id codex-session-42 \
+  --harness codex \
+  --json
+```
+
+Before acceptance, the receiver must inspect the immutable snapshot and
+reconcile all of its freshness bindings: the work-state fingerprint, contract
+identity, route identity, selected guides, current repository branch, current
+repository HEAD, changed paths, and the origin of the event ledger. Receiving a
+file or message is not acceptance. `handoff-accept` is run only when the
+receiving harness actually consumes the handoff.
+
+Acceptance retry semantics are deterministic: retrying with the same
+`consumerId` returns the existing operational receipt idempotently; a different
+consumer fails with `E_HANDOFF_ALREADY_ACCEPTED`. An old unbound handoff remains
+readable for historical continuity but is not acceptable and returns
+`E_HANDOFF_ACCEPTANCE_UNBOUND`.
+
 ---
 
 ## 4. Harness A — Recording Handoff Context
@@ -251,3 +278,61 @@ Every discovery adapter (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.m
 > Discover task namespaces with ForgeLoop; if exactly one active task is healthy it may be selected implicitly; if multiple active tasks exist, select with `--task` or `FORGELOOP_TASK`.
 > Inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`.
 > A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+
+---
+
+## 8. Canonical Handoff Acceptance & State Binding
+
+### 8.1 Work-State Binding
+
+Handoff envelopes (`.forgeloop/task-state/<taskKey>/handoffs/handoff-*.json`) bind to the exact lifecycle state snapshot at creation time via `state.workStateFingerprint`.
+The envelope itself remains strictly immutable after creation.
+A handoff is acceptable only when both canonical state and the current repository
+checkout still match that immutable snapshot. A clean Git HEAD or branch change
+can make a handoff stale even when the worktree has no uncommitted changes.
+
+### 8.2 Exactly-Once Handoff Acceptance
+
+Harnesses taking ownership of an existing handoff record their acceptance into the task event ledger using `handoff-accept`:
+
+```bash
+forgeloop handoff-accept \
+  --task auth-feature \
+  --handoff handoff-001 \
+  --consumer-id agent-session-42 \
+  --harness cursor \
+  --json
+```
+
+Acceptance enforces:
+
+1. **Unbroken Binding**: Handoff must contain `workStateFingerprint` (legacy unbound handoffs fail with `E_HANDOFF_ACCEPTANCE_UNBOUND`).
+2. **Freshness**: Work state, contract fingerprint, route fingerprint, changed paths, and the directly observed current repository branch and HEAD must match the handoff snapshot (any drift fails with `E_HANDOFF_STALE`).
+3. **Single Consumer**: The handoff can be accepted by at most one consumer. If another consumer attempts acceptance, it fails with `E_HANDOFF_ALREADY_ACCEPTED`. Retrying with the same `consumerId` is idempotent.
+4. **Ledger Integrity**: An immutable `HANDOFF_ACCEPTED` event is appended to `events.ndjson`.
+
+Acceptance is exactly-once operational receipt only. It does not transfer claims,
+delegate work, authorize actions, approve review, or create verification evidence.
+
+### 8.3 Acceptance Inspection
+
+Commands `handoff-show` and `handoff-list` project current acceptance status:
+
+- `OPEN`: Handoff is valid, bound, and waiting for acceptance.
+- `ACCEPTED`: Successfully accepted by a specific consumer.
+- `UNBOUND`: Legacy handoff envelope lacking work-state binding.
+- `INCONSISTENT`: Digest, ledger validation, or acceptance event mismatch detected. An unreadable or invalid ledger is never projected as `OPEN` or `ACCEPTED`; its unique sorted ledger error codes are exposed as `reasonCodes`.
+
+### 8.4 Semantic Continuity Linting
+
+When running `forgeloop reconcile-continuity`, ForgeLoop executes deterministic
+semantic lint checks against schema-valid operational hints. It warns when a
+remaining-work item or current focus ID is already in `state.completedSteps`,
+when an ID appears in both `remainingWork` and `knownIssues`, or when a relative
+`inspectFirst` path is missing from the target. If all operational hints are
+empty, it emits the informational `CONTINUITY_EMPTY_HINT_SET` finding while the
+lint status remains `PASS`.
+
+Lint results use `{ status: "PASS" | "WARN", findings: [...] }`. They are
+non-authoritative, non-evidence diagnostics and do not change reconciliation
+classification or lifecycle state.

package/docs/DOCUMENTATION_GUIDE.md

@@ -38,6 +38,13 @@ MCP package boundary    -> MCP package tests + scripts/mcp-package-smoke.mjs
 
 Operational documentation must explain canonical behavior, not redefine it.
 
+Terminology must remain consistent across active documents: say “advisory
+context,” not “canonical memory”; “handoff acceptance,” not “ownership
+transfer”; and “operational receipt,” not “delegation.” Advisory output is
+never canonical state, evidence, authority, completion truth, or next-action
+authority. `consumerId`, harness names, recipient hints, and transport labels
+are descriptive values rather than authenticated identity or authority.
+
 Documentation-impact questions for integration/MCP changes:
 
 - Did a server mode or capability gate change?

package/docs/GETTING_STARTED.md

@@ -439,6 +439,8 @@ the workflow needs those boundaries:
 forgeloop handoff-create --task <taskId> --note "Continue verification" --json
 forgeloop handoff-list --task <taskId> --json
 forgeloop handoff-show --task <taskId> --id <handoffId> --json
+forgeloop handoff-accept --task <taskId> --handoff <handoffId> \
+  --consumer-id <consumerId> --harness <harness> --json
 forgeloop responsibility-set --task <taskId> --label implementation --allowed-path src --required-check unit-tests --json
 forgeloop responsibility-status --task <taskId> --json
 ```
@@ -450,6 +452,26 @@ not delegation or evidence. A responsibility label is descriptive, not a
 coder/reviewer/cleaner role, and its allowed paths, required checks, and frozen
 inputs are mechanically enforced when present.
 
+### Optional advisory context
+
+An embedding host may inject an advisory provider through the Integration API
+when extra context is useful. This is not part of the minimum quickstart:
+
+```javascript
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "host-context": {
+      id: "host-context",
+      recall: async ({ query }) => ({ items: await hostLookup(query) }),
+    },
+  },
+});
+```
+
+Recall is explicit, lazy, bounded, and non-persisted. Provider output is never
+state, evidence, authority, completion truth, or executable instructions. See
+[`ADVISORY_CONTEXT.md`](./ADVISORY_CONTEXT.md) for the full contract.
+
 ### Differential Verification Scope
 
 Configure a trusted scoped checker only when it can consume canonical paths:

package/docs/KNOWLEDGE_SOURCES.md

@@ -8,6 +8,16 @@ Target: ForgeLoop 1.8.0 at current `main` state at review start
 This ledger records research inputs for the knowledge-integration review. It is
 not an endorsement list, a source-content mirror, or an evidence registry.
 
+## Current optional provider source class
+
+This note is an operational boundary added after the historical snapshot above;
+it does not rewrite that review's target version or accepted sources. A host may
+provide external advisory context through the ForgeLoop Integration API, but a
+knowledge source is not canonical task state, evidence, authority, completion,
+or next-action authority. Provider results remain lazy, opt-in, bounded, and
+non-persisted; provenance belongs to the host unless a separately versioned
+canonical artifact is introduced.
+
 ## User-provided revised plan
 
 Source: user-provided `FORGELOOP_LUNA_KNOWLEDGE_INTEGRATION_PLAN_REVISED.md`

package/docs/MCP.md

@@ -25,6 +25,9 @@ Two transports ship in one package:
 - **Recovery acknowledgement is not authorization.** `acknowledgeRecovery`
   in tool input only satisfies ForgeLoop's caller acknowledgement after the
   server was started with recovery capability.
+- **Advisory context is host-injected only.** The core Integration API supports
+  explicit provider injection, but the stock MCP adapter must not fabricate,
+  auto-discover, or persist an advisory provider or its results.
 
 ## Modes
 
@@ -84,6 +87,19 @@ content.
 Raw recovery artifacts, transaction journals, lock files, and unbounded event
 ledgers are intentionally not exposed.
 
+The `handoff-accept` mutating command is available only through a mode that
+allows loop mutations; `readonly` intentionally hides it. When exposed, it
+records one canonical `HANDOFF_ACCEPTED` operational receipt and preserves the
+same freshness, consumer-idempotency, ledger, and no-claim-transfer rules as
+the CLI and Integration API. MCP transport metadata cannot authenticate a
+`consumerId`, establish authority, or turn receipt of a message into
+acceptance.
+
+Advisory provider recall is not a stock MCP resource or command. A host that
+needs advisory context injects a provider into the core Integration API and
+performs an explicit bounded recall itself. MCP must never auto-recall context
+for startup, status, next, task/context, or any other canonical projection.
+
 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
@@ -119,7 +135,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.9.x` |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current release `1.10.0` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |

package/docs/RECIPES.md

@@ -457,6 +457,86 @@ operational context only: a handoff is not delegation, authority, independent
 review evidence, or completion evidence. Use `continuity.json` for mutable
 resume notes and canonical execution artifacts for proof.
 
+### Recipe 18A — Accept an Immutable Handoff Exactly Once
+
+After inspecting the snapshot and confirming that the receiving harness is
+actually consuming it, record the operational receipt:
+
+```bash
+forgeloop handoff-accept --task task-001 \
+  --handoff <handoffId> \
+  --consumer-id agent-session-42 \
+  --harness codex \
+  --json
+```
+
+Retrying with the same consumer is idempotent. A different consumer receives
+`E_HANDOFF_ALREADY_ACCEPTED`. Acceptance is operational only: it does not
+transfer claims, create evidence, approve delegation, or grant authority.
+
+### Recipe 18B — Diagnose an Inconsistent Handoff
+
+Inspect the derived projection and ledger before attempting any repair:
+
+```bash
+forgeloop handoff-list --task task-001 --json
+forgeloop handoff-show --task task-001 --id <handoffId> --json
+forgeloop validate-protocol --task task-001 --json
+```
+
+`INCONSISTENT` is fail-closed. Check the returned reason codes for a stale
+contract/route/repository snapshot, an unbound legacy handoff, a digest mismatch,
+or invalid acceptance history. Do not edit the immutable handoff or
+`events.ndjson`; create a fresh handoff after the canonical issue is resolved.
+
+### Recipe 18C — Use an Advisory Provider from a Host Integration
+
+Register a provider in runtime context and invoke recall explicitly:
+
+```javascript
+import {
+  createForgeLoopContext,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "host-context": {
+      id: "host-context",
+      recall: async ({ query }) => ({ items: await hostLookup(query) }),
+    },
+  },
+});
+
+const result = await recallAdvisoryContext({
+  target: ".",
+  taskId: "task-001",
+  providerName: "host-context",
+  query: "current authentication constraints",
+  runtimeContext,
+});
+```
+
+Recall is lazy, bounded, opt-in, non-persisted, non-evidence, and
+non-executable. Validate every proposed change against canonical state and
+verification instead of executing provider text.
+
+### Recipe 18D — Resume with Continuity Lint Warnings
+
+Treat lint findings as inspection hints only:
+
+```bash
+forgeloop continuity --task task-001 --json
+forgeloop reconcile-continuity --task task-001 --json
+forgeloop next --task task-001 --json
+```
+
+Findings such as `CONTINUITY_REMAINING_ALREADY_COMPLETED`,
+`CONTINUITY_FOCUS_ALREADY_COMPLETED`, `CONTINUITY_ITEM_ROLE_CONFLICT`,
+`CONTINUITY_INSPECT_PATH_MISSING`, and `CONTINUITY_EMPTY_HINT_SET` are
+non-authoritative and non-evidence. Refresh the note with
+`record-continuity` when useful, then follow the canonical next action.
+
 ---
 
 ### Recipe 19 — Apply a Responsibility Contract

package/docs/RELEASE_CHECKLIST.md

@@ -16,6 +16,20 @@ preparation and verification checklist; it does not authorize publication.
 
 ## Protocol and attestation
 
+- [ ] `protocol-info` and the Integration API capability contracts agree.
+- [ ] `canonicalHandoffs` v2 is advertised consistently.
+- [ ] `advisoryContextProviders` v1 is advertised consistently.
+- [ ] Advisory context remains Integration-API-only.
+- [ ] `next`, `status`, and `task/context` invoke zero advisory providers.
+- [ ] Advisory request budgets are normalized before provider invocation.
+- [ ] Advisory results are never persisted by ForgeLoop.
+- [ ] Same-consumer handoff acceptance is idempotent.
+- [ ] Different-consumer handoff acceptance fails closed.
+- [ ] Concurrent acceptance creates one `HANDOFF_ACCEPTED` event.
+- [ ] Clean HEAD/branch drift rejects handoff acceptance.
+- [ ] Stale contract/route identity rejects handoff creation or acceptance.
+- [ ] An invalid event ledger projects `INCONSISTENT`.
+- [ ] Continuity lint remains non-authoritative and non-evidence.
 - [ ] `npm run dependency:policy` passes without adding runtime dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.

package/docs/TROUBLESHOOTING.md

@@ -761,16 +761,50 @@ explicit operation only when the task's scope permits it.
 
 ---
 
+### Symptom: Advisory Context Recall Is Unavailable or Rejected
+
+#### Error Codes: `E_ADVISORY_CONTEXT_PROVIDER_INVALID`, `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE`, `E_ADVISORY_CONTEXT_QUERY_INVALID`, `E_ADVISORY_CONTEXT_REQUEST_INVALID`, `E_ADVISORY_CONTEXT_RESULT_INVALID`, `E_ADVISORY_CONTEXT_TIMEOUT`, `E_ADVISORY_CONTEXT_OUTPUT_LIMIT`, `E_PORTABLE_CONTEXT_INVALID`
+
+#### What it means
+
+The host's optional advisory provider is missing, malformed, unavailable, too
+slow, or returned content outside the bounded portable-context contract. These
+failures never become lifecycle, evidence, completion, or next-action failures.
+
+#### Safe recovery
+
+Inspect provider registration and normalize the request before retrying through
+the Integration API. Reduce query, item, total-output, and timeout values to the
+documented budgets, remove secrets/control characters, and ensure the provider
+returns only allowlisted item fields. If advisory context is unavailable,
+continue from canonical task state; do not fabricate a provider or execute its
+text.
+
+### Symptom: Continuity Lint Reports a Contradictory Hint
+
+Continuity lint is diagnostic only. Its findings do not change reconciliation,
+state, evidence, authority, or completion:
+
+| Finding | Meaning | Safe response |
+| --- | --- | --- |
+| `CONTINUITY_REMAINING_ALREADY_COMPLETED` | A remaining-work item is already recorded as completed. | Refresh the operational note; do not change canonical completion evidence. |
+| `CONTINUITY_FOCUS_ALREADY_COMPLETED` | The current focus ID is already completed. | Choose a current inspection focus or clear the hint. |
+| `CONTINUITY_ITEM_ROLE_CONFLICT` | An item appears in both remaining work and known issues. | Remove the contradictory hint through `record-continuity`. |
+| `CONTINUITY_INSPECT_PATH_MISSING` | An `inspectFirst` path is not present in the current target. | Reconcile the checkout and update the path hint. |
+| `CONTINUITY_EMPTY_HINT_SET` | No operational hint was supplied. | Treat the result as informational and follow canonical `next`. |
+
 ### Symptom: Handoff Is Invalid or Tampered
 
-#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`
+#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`, `E_HANDOFF_STALE`, `E_HANDOFF_ALREADY_ACCEPTED`, `E_HANDOFF_ACCEPTANCE_INCONSISTENT`
 
 #### What it means
 
 The immutable handoff envelope is malformed, its state is unavailable, its
 digest no longer matches, or the requested snapshot does not exist. A handoff
 note is not delegation, authority, independent review evidence, or completion
-evidence.
+evidence. Acceptance is exactly-once operational receipt only. The current
+repository branch and HEAD are checked directly, so clean committed checkout
+drift can make a handoff stale even when changed paths are empty.
 
 #### Safe recovery
 
@@ -781,6 +815,12 @@ forgeloop continuity --task <id> --json
 forgeloop reconcile-continuity --task <id> --json
 ```
 
+If `handoff-list` or `handoff-show` reports `INCONSISTENT`, inspect the
+`reasonCodes` field. The commands validate the event ledger before projecting
+acceptance and never turn an unreadable or invalid ledger into an empty ledger.
+Repair the named ledger through the canonical protocol workflow; do not edit
+`events.ndjson` by hand.
+
 Use the last valid handoff or continuity only to focus inspection, then trust
 the canonical task state and checkout. Never repair a handoff by editing or
 deleting its JSON file.
@@ -1002,6 +1042,13 @@ current-cycle validation.
 | `E_ACTION_STATE_MISMATCH` | Requested durable action transition is not part of the canonical state machine. | Inspect current action state with forgeloop action-show and use a legal transition; never edit action artifacts by hand. |
 | `E_ACTION_VERIFICATION_INVALID` | Verification evidence does not resolve to a canonical passed ForgeLoop artifact bound to this task and action. | Supply a canonical execution or check reference produced by run-check for this task; arbitrary strings fail closed. |
 | `E_ACTION_VERIFICATION_REQUIRED` | The action cannot reach VERIFIED through this surface; canonical independent postcondition evidence is required. | Run an independent verification check, then record it with forgeloop action-verify; exit code 0 alone is not verification. |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | Advisory context output exceeded the configured character or item limit. | Reduce query scope, limit items, or truncate oversized summaries at the provider. |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` | Advisory context provider configuration or interface implementation is invalid. | Use a provider implementing id, recall(input) with bounded query parameters; advisory context is optional. |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | Requested advisory context provider is not registered in runtime context. | Register the provider in runtime context before recall, or proceed without advisory context; provider failure never blocks canonical lifecycle. |
+| `E_ADVISORY_CONTEXT_QUERY_INVALID` | Advisory context query failed portable-context validation or exceeded budget. | Provide a bounded query free of control characters and secret-like values. |
+| `E_ADVISORY_CONTEXT_REQUEST_INVALID` | Advisory context recall budgets are not finite integer values within the supported request contract. | Provide finite integer limit, maxItemChars, maxTotalChars, and timeoutMs values; oversized valid values are clamped to documented maxima. |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | Advisory context provider returned an invalid result structure. | Ensure provider returns items with string summary and optional title, sourceRef, observedAt, confidence. |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Advisory context recall exceeded its execution timeout. | Use a responsive provider or increase timeout within limits; advisory context is optional. |
 | `E_APPROVAL_ALREADY_RESOLVED` | Approval is one-time resolvable and has already been approved or rejected. | Request a new approval if another decision is required. |
 | `E_APPROVAL_INVALID` | Approval artifact is malformed or does not bind the required fingerprint tuple. | Request a new approval with forgeloop approval-request; never hand-edit approval artifacts. |
 | `E_APPROVAL_STALE` | Approval no longer matches the current action fingerprint, contract fingerprint, task revision, or capability. | Request and resolve a fresh approval against the current action revision. |
@@ -1090,8 +1137,12 @@ current-cycle validation.
 | `E_GATE_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_GATE_STALE` | Referenced gate artifact changed after approval. | Update artifact SHA-256 in gate file. |
 | `E_GATE_UNVERIFIED` | 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_HANDOFF_ACCEPTANCE_INCONSISTENT` | Handoff acceptance disagrees with task event ledger history. | Verify ledger integrity and require a preceding valid HANDOFF_CREATED event. |
+| `E_HANDOFF_ACCEPTANCE_UNBOUND` | Handoff snapshot lacks required workStateFingerprint binding. | Create a fresh handoff from the current ForgeLoop version before accepting it. |
+| `E_HANDOFF_ALREADY_ACCEPTED` | Handoff was already accepted by a different consumer. | Create a new handoff for the new consumer; do not manually edit acceptance events. |
 | `E_HANDOFF_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_HANDOFF_NOT_FOUND` | 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_HANDOFF_STALE` | Handoff snapshot has drifted from the current canonical task state or repository. | Create a new fresh handoff from the current task state instead of accepting a stale snapshot. |
 | `E_HANDOFF_STATE_UNAVAILABLE` | 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_HANDOFF_TAMPERED` | 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_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID` | Hypothesis disposition evidence references do not resolve to checks of the active cycle. | Reference at least one check ID recorded in the active verification cycle. |
@@ -1124,6 +1175,7 @@ current-cycle validation.
 | `E_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
 | `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
 | `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
+| `E_PORTABLE_CONTEXT_INVALID` | Text or object failed portable-context safety, character, or secret limits. | Ensure text is bounded, contains no control characters, and contains no secret-like values. |
 | `E_PREFLIGHT_EVENT_MISSING` | 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_PREFLIGHT_GATES_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_PREFLIGHT_GATE_EVENT_MISSING` | 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. |

package/docs/UNIVERSAL_INTEGRATION.md

@@ -93,6 +93,66 @@ commands in [`EXECUTION_PROFILE_BENCHMARKS.md`](./EXECUTION_PROFILE_BENCHMARKS.m
 The benchmark source policy accepts provider or host observations only and
 keeps unavailable or non-comparable measurements out of efficiency claims.
 
+### Advisory Context & Handoff Acceptance
+
+Capability negotiation is feature-first: `canonicalHandoffs` is v2 and
+`advisoryContextProviders` is v1. These capability-family versions are
+independent of Protocol v1, schema v1, and Integration API v1. The programmatic
+integration API exposes lazy advisory context querying and exactly-once handoff
+acceptance:
+
+```javascript
+import {
+  createForgeLoopContext,
+  recallAdvisoryContext,
+  acceptCanonicalHandoff,
+  resolveHandoffAcceptance,
+} from "@cassiomc1/forgeloop/integration";
+
+// 1. Register host-provided advisory context
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "host-memory": {
+      id: "host-memory",
+      recall: async ({ query }) => ({ items: [...] }),
+    },
+  },
+});
+
+// 2. Explicitly query advisory context (strictly non-evidence, non-executable)
+const advisoryResult = await recallAdvisoryContext({
+  target: ".",
+  taskId: "task-1",
+  providerName: "host-memory",
+  query: "authentication tokens",
+  runtimeContext,
+});
+
+// 3. Exactly-once handoff acceptance
+const acceptance = await acceptCanonicalHandoff(".", {
+  taskId: "task-1",
+  handoffId: "handoff-001",
+  consumerId: "agent-session-42",
+  harness: "cursor",
+});
+```
+
+See [`ADVISORY_CONTEXT.md`](./ADVISORY_CONTEXT.md) for full trust boundary specifications, portable text sanitization rules, and budget enforcement.
+
+Advisory recall budgets are normalized before provider dispatch: valid oversized
+integer requests are clamped, while invalid finite/integer/minimum types fail
+with `E_ADVISORY_CONTEXT_REQUEST_INVALID` before provider lookup. The registry
+key and resolved provider `id` must match. Handoff acceptance independently
+checks canonical state and the current repository branch/HEAD, and remains an
+exactly-once operational receipt with no evidence, claim transfer, or authority.
+
+Advisory context is not a canonical resource unless a future explicitly
+versioned resource introduces one. `protocol-info` advertises the optional
+provider capability, but the stock CLI never recalls it automatically and
+there is no stock `context-recall` command. A consumer that only understands
+`canonicalHandoffs` v1 may disable only the handoff-specific UI while retaining
+the rest of Protocol v1 functionality.
+
 ## Consumers
 
 | Surface | Entry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -51,6 +51,7 @@
     "docs/assets/diagrams",
     "docs/GETTING_STARTED.md",
     "docs/CROSS_HARNESS_CONTINUITY.md",
+    "docs/ADVISORY_CONTEXT.md",
     "docs/CLI_REFERENCE.md",
     "docs/ARTIFACT_REFERENCE.md",
     "docs/TROUBLESHOOTING.md",

package/schemas/handoff-envelope.schema.json

@@ -27,6 +27,7 @@
         "phase": { "type": "string", "minLength": 1 },
         "revision": { "type": "integer", "minimum": 0 },
         "verificationCycle": { "type": "integer", "minimum": 1 },
+        "workStateFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
         "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
         "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
         "repositoryFingerprint": { "type": "object" },