@cassiomc1/forgeloop 1.9.0 → 1.10.1

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.1
 
 ## 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. |

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 -->
@@ -1203,3 +1217,18 @@ For `BASELINE` artifacts and `PASS`/`FAIL` evaluations, `sourceMaterialFingerpri
 and stable `sourceObservation` are conditionally required; their before and after
 fingerprints must equal the bound source fingerprint. `BLOCKED` and
 `NOT_OBSERVED` artifacts may omit these observed-source fields.
+
+## Transaction diagnostics and retention
+
+`.forgeloop/.txn/<transactionId>/manifest.json` records transaction identity,
+status, staged writes, and recovery diagnostics. `COMMITTED`, `ROLLED_BACK`,
+and `ABORTED` are terminal; an aborted staging callback did not publish its
+staged writes. A successful recovery is not reported as incomplete on the next
+doctor inspection. The transaction lock still protects recovery from live
+writers.
+
+The repository maintenance command described in
+[CONTRIBUTING.md](../CONTRIBUTING.md#focused-verification-and-maintenance)
+compacts eligible stage/backup payloads only. It retains manifests and ledgers,
+so historical manifest enumeration remains linear. These diagnostics are not
+substitutes for a valid execution receipt or external-action reconciliation.

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/CODE_ATTESTATION.md

@@ -139,3 +139,12 @@ distinguished from invalid attestations by the stable exit-code contract:
 
 See [`REVISION_PROVIDERS.md`](./REVISION_PROVIDERS.md) and
 [`SIGNING_PROVIDERS.md`](./SIGNING_PROVIDERS.md) for extension boundaries.
+
+## Receipt availability in repository CI
+
+The repository audit workflow checks supplied task receipts individually with
+an explicit task ID. A checkout without a receipt reports `NOT_VERIFIED`.
+That is absence of lifecycle evidence, not an attestation trust level; it does
+not mean `PROCESSED`, `VERIFIED`, or `ATTESTED`. CI does not fabricate a receipt
+from successful repository tests. Transaction payload compaction preserves
+the manifests and ledgers needed to inspect the original history.

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

@@ -24,12 +24,12 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 When updating documentation, always derive content from its authoritative source:
 
 ```text
-CLI syntax truth        -> CLI registry / parser (src/cli.js, src/core/cli-command-definitions.js, src/core/cli-metadata.js)
+CLI syntax truth        -> CLI registry / parser (src/cli.js, src/core/cli-command-definitions.js)
 Artifact shape truth    -> JSON schemas (schemas/*.schema.json, src/core/artifact-registry.js)
 Lifecycle truth         -> protocol / state machine (src/core/protocol.js)
 Reason-code truth       -> exported protocol constants (src/core/error-codes.js, src/core/protocol.js)
 Guide registry truth    -> canonical guide registry (src/config/guides.json)
-Package contents truth  -> package.json + package tests (tests/package.test.js)
+Package contents truth  -> package.json + docs/PACKAGE_CONTENTS.md + package tests (tests/package.test.js)
 Documentation routing   -> DOCS_INDEX.md
 Integration API truth   -> src/integration.js (exports, envelope, limits, risk classes, resources)
 MCP behavior truth      -> integrations/mcp/src/* and integrations/mcp/package.json
@@ -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?
@@ -112,7 +119,7 @@ conformance checks detect omissions.
 
 | Documentation Area | Canonical Machine Source | Conformance Validator |
 | --- | --- | --- |
-| **CLI commands & flags** | `CLI_COMMAND_METADATA` (`src/core/cli-metadata.js`) & `src/cli.js` | `scripts/validate_documentation_conformance.mjs` |
+| **CLI commands & flags** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) & `src/cli.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Artifact paths** | `ARTIFACT_REGISTRY` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Artifact fields & types** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Enums & consts** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
@@ -121,7 +128,7 @@ conformance checks detect omissions.
 | **Stable error codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `scripts/validate_documentation_conformance.mjs` |
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
 | **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
-| **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
+| **Package-shipped docs and runtime** | `package.json` (`files`) + `docs/PACKAGE_CONTENTS.md` | `tests/package.test.js` + `scripts/package_smoke.mjs` |
 | **Architecture and trust diagrams** | `docs/diagrams/manifest.json` plus each typed workflow source | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---

package/docs/EXECUTION_PROFILE_BENCHMARKS.md

@@ -421,3 +421,13 @@ The source policy is intentionally narrow: provider or host observations are
 accepted for benchmark claims, while actor-reported or absent telemetry stays
 non-comparable. This is an efficiency observation boundary, not verification
 evidence and not an external publication result.
+
+## Contract signals and exclusions
+
+Profile selection reads string and structured success/verification
+requirements, including nested requirements and explicit publication or
+production-readiness types. Constraints and stop conditions describe
+boundaries and are excluded from obligation scanning. For example, a
+constraint saying “No publication” does not create a publication requirement.
+An explicit route risk remains authoritative and can still raise the safety
+floor. Profiles classify work; they do not grant execution authority.

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.1` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |
@@ -171,3 +187,15 @@ list in [TROUBLESHOOTING](./TROUBLESHOOTING.md):
 
 Canonical ForgeLoop errors (e.g. `E_TASK_SCOPE_CONFLICT`,
 `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`) are always preserved verbatim.
+
+## Reproducible adapter verification
+
+The adapter commits its own lockfile and declares both server and test-client
+SDK versions. `npm run mcp:setup` installs that lock with lifecycle scripts
+disabled, then substitutes the locally packed core offline. Packed smoke uses
+the same dependency graph and substitutes both local tarballs using the system
+`tar` command. This replacement does not resolve registry metadata or require a
+warm npm cache; `npm ci` still retrieves the locked dependencies. Both paths
+verify resolved dependency versions and print lock/tarball SHA-256 identities.
+The adapter remains a separate package; these dependencies are not added to
+the ForgeLoop core runtime.