@cassiomc1/forgeloop 1.9.0 → 1.10.1

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,17 +25,20 @@ 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 |
 | Knowledge sources and provenance | [`docs/KNOWLEDGE_SOURCES.md`](./docs/KNOWLEDGE_SOURCES.md) | Snapshot, licensing observations, source roles, accepted/skipped concepts, and reuse boundaries |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Current release checklist | [`docs/RELEASE_CHECKLIST.md`](./docs/RELEASE_CHECKLIST.md) | Package, protocol, attestation, integration, and publication gates |
+| Core npm package contents | [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md) | Published consumer surface, intentional inclusions, exclusions, and clean-room verification |
 | ForgeLoop 1.6.1 release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_6_1.md`](./docs/RELEASE_CHECKLIST_1_6_1.md) | Verification adapter boundary, isolation invariants, and publication gates |
 | ForgeLoop 1.5/MCP release checklist (historical) | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
 | ForgeLoop 1.4 release checklist | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) | Claim-recovery, compatibility, package, and publication gates |
@@ -55,6 +58,13 @@ integration and guide context. Use this map before editing documentation.
 | Code Attestation Chain | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#completion-flow) | Completion, exact-content manifest, in-toto statement, optional signing, and range coverage |
 | Real Execution Proof of Concept (PoC) | [`poc/README.md`](./poc/README.md) | Non-normative, reproducible public engineering workload, audit evidence, and technical audit. Normative behavior remains owned by [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md). |
 
+## Recent implementation review
+
+The repository-local [Astra implementation record](./docs/ASTRA_IMPLEMENTATION.md)
+maps the completed findings to code, tests, measurements, and remaining limits.
+Use the canonical guides below for operational instructions; the audit record
+is historical evidence and is not part of the published core package.
+
 ## Audience map
 
 | I am a... | Start here |
@@ -96,6 +106,7 @@ integration and guide context. Use this map before editing documentation.
 - **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Map ForgeLoop state into an external runtime/orchestrator**: [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md)
 - **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
+- **Audit the npm package boundary**: [`docs/PACKAGE_CONTENTS.md`](./docs/PACKAGE_CONTENTS.md)
 - **Verify source-content attestations**: [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **Understand narrow verification and checker binding**: [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope)
 - **Inspect the governed diagrams**: [`docs/diagrams/README.md`](./docs/diagrams/README.md)

package/LOOP_ENGINEERING.md

@@ -393,8 +393,8 @@ DESTRUCTIVE_ACTION_REQUIRED
 ```
 
 Multiple reasonable aesthetic or positioning choices do not justify a question.
-The deterministic support helper in `src/core/decision-classification.js`
-validates this boundary; it does not use an LLM or parse natural language.
+The executable test example in `tests/helpers/decision-classification.js`
+illustrates this boundary; runtime authority remains with this protocol and the task contract. The example does not use an LLM or parse natural language.
 
 ### Contract-before-clarification sequence
 
@@ -508,8 +508,8 @@ The compatibility distinction is explicit:
 "Installed" and "compatible" are different claims. A harness can have an
 external workflow installed and still be `INCOMPATIBLE WITH AUTONOMOUS MODE`.
 Use that wording instead of calling the workflow broken. The deterministic
-support helper in `src/core/workflow-compatibility.js` evaluates this boundary;
-it does not modify `src/core/decision-classification.js`, invoke an LLM, or
+test example in `tests/helpers/workflow-compatibility.js` exercises this boundary;
+it does not modify `tests/helpers/decision-classification.js`, invoke an LLM, or
 redesign a runtime, arbiter, supervisor, or approval broker.
 
 For the sixth blind conformance run, exclude mandatory-approval workflows at
@@ -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;
@@ -528,3 +561,26 @@ canonical trace/reflection evidence. They preserve unknown usage values and
 only compare efficiency when a project-local reference scenario exists. The
 existing diagnostic and reflection model remains the authority for information
 gain, intervention effectiveness, failure signatures, and oscillation.
+
+## Transaction identity and diagnostic retention
+
+The transaction context binds the physical project root and task ID. Nested
+operations reject cross-project reuse, even when task IDs match. Filesystem
+aliases of the same physical project remain compatible. Reads and writes of
+transaction-aware artifacts enforce the same project boundary.
+
+Committed transactions, successful rollbacks, and failures aborted before
+publication are terminal. `doctor --fix` recovers eligible committing
+transactions under their task locks, then recomputes incomplete findings.
+This does not imply that an ambiguous external action was reconciled.
+
+Repository maintenance can preview or compact old terminal stage/backup
+payloads with `npm run transactions:compact`. Manifests and event ledgers
+remain intact; recent, ambiguous, invalid, locked, and unsafe records are
+preserved. See [maintenance usage](CONTRIBUTING.md#focused-verification-and-maintenance).
+
+Lifecycle selection keeps common identity, freshness, gates, and chronology
+checks ahead of phase-specific resolvers. Planning, verification, review,
+recovery, and pending-action modules organize decisions without changing that
+precedence. Executable protocol examples under `tests/helpers` are test
+fixtures, not runtime policy authorities.

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

@@ -106,8 +106,8 @@ are both present:
 | Protocol activation resumability | `src/core/resumability.js`, READY consistency checks, event matrix, and `next` repair semantics | `tests/resumable-protocol.test.js` |
 | Hidden kit layout | `src/core/target-layout.js`, safe init/update migration, manifest layout version, native shims, and profile resolver | `tests/hidden-layout.test.js`, package and compatibility tests |
 | Contextual frontend taste | `ENG/taste-frontend-eng.md`, router metadata, attribution, and design/accessibility precedence | `tests/taste-guide.test.js`, route fixtures |
-| Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `src/core/decision-classification.js`, `src/core/workflow-compatibility.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/workflow-compatibility.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
-| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `src/core/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
+| Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `tests/helpers/decision-classification.js`, `tests/helpers/workflow-compatibility.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/workflow-compatibility.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
+| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `tests/helpers/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
 | Instruction-conflict handling — structural | Canonical source-attribution and `WORKFLOW_CONFLICT` policy in `LOOP_ENGINEERING.md` plus adapter references | `tests/autonomy-policy.test.js`, `tests/workflow-compatibility.test.js` |
 | Autonomous-mode precedence — structural | Autonomous/interactive mode contract and harness exclusion metadata | `tests/workflow-compatibility.test.js`, `tests/conformance-scenarios.test.js` |
 | Pre-contract autonomy — cross-agent live robustness | Prior third blind-run result, `conformance/runs/2026-08-13-codex-fourth-live.md`, preserved fifth-run report `conformance/runs/2026-08-13-codex-fifth-live.md`, and the exact blind request | `tests/conformance-scenarios.test.js`; sixth run is not started until mandatory approval is excluded |

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
@@ -422,6 +462,19 @@ validator-backed completion. Drift reopens verification, and migration keeps
 modified or unmanaged files for review. The terminal result is one of
 `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or `INVALID`.
 
+Before execution, profile selection reads structured obligations and explicit
+risks; exclusion constraints are not required actions. After a blocked
+preflight and contract revision, `next` may guide a checkpoint refresh through
+`clear-state` and a fresh preflight. This path requires a valid pre-execution
+ledger and routing bound to the revised contract. Execution transactions bind
+the physical project and task; a matching task ID in another project cannot
+reuse them. See [recovery guidance](./docs/TROUBLESHOOTING.md#revised-contract-after-a-blocked-preflight).
+
+CI audits each supplied task receipt explicitly. With no receipt it reports
+`NOT_VERIFIED`; green repository tests alone do not establish lifecycle
+completion or attestation. For contributor checks and safe payload retention,
+see [CONTRIBUTING.md](./CONTRIBUTING.md#focused-verification-and-maintenance).
+
 ## Protocol compatibility
 
 The npm package version is independent of protocol version. The current

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'