@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/docs/ARTIFACT_REFERENCE.md

@@ -35,6 +35,7 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `task-state/<task-key>/approvals/approval-<id>.json` | `approval` | Protocol Managed | Append Decision Once | Action Approval Attestation |
 | `policy/capabilities.json` | `capability-policy` | Operator Or Agent | Mutable Configuration | Capability Policy Specification |
 | `task-state/<task-key>/evaluations/eval-<id>.json` | `trajectory-evaluation` | Protocol Compiled | Immutable Once Written | Trajectory Evaluation |
+| `task-state/<task-key>/structural-quality/baseline.json` | `structural-quality` | Protocol Compiled | Baseline Immutable After Execution | Structural Quality Evidence |
 | `task-state/<task-key>/usage.json` | `usage` | Actor Or Trusted Host | Overwritten On Usage Record | Informational Usage Telemetry |
 | `task-state/<task-key>/workspace-binding.json` | `workspace-binding` | Protocol Generated | Immutable After Bind | Workspace Identity Binding |
 | `task-state/<task-key>/handoffs/handoff-<id>.json` | `handoff-envelope` | Protocol Compiled | Immutable Once Written | Canonical Handoff Snapshot |
@@ -165,6 +166,7 @@ Readiness attestation evaluated prior to implementation.
 - `fingerprints` *(object, optional)*
 - `sources` *(object, optional)*
 - `policy` *(object, optional)*
+- `structuralQuality` *(object, optional)*
 
 <!-- END FORGELOOP GENERATED: schema:preflight -->
 
@@ -250,6 +252,28 @@ Local ForgeLoop configuration settings and policy bindings.
 - `policy` *(string, optional, minLength: 1)*
 - `requiredGates` *(array<string>, optional)*
 - `requiredEvidence` *(array<string>, optional)*
+- `structuralQuality` *(object, optional)*
+  - `mode` *(string, optional, enum: `off`, `observe`, `gate`)*
+  - `provider` *(string, optional, pattern: `^[a-z][a-z0-9-]{0,63}$`)*
+  - `maxRegressionPoints` *(integer, optional, minimum: 0, maximum: 10000)*
+  - `dimensionBudgets` *(dimensionMap, optional)*
+    - `modularity` *(integer or null, optional)*
+    - `acyclicity` *(integer or null, optional)*
+    - `depth` *(integer or null, optional)*
+    - `equality` *(integer or null, optional)*
+    - `redundancy` *(integer or null, optional)*
+  - `forbidNewCycles` *(boolean, optional)*
+  - `minQualitySignal` *(integer or null, optional)*
+  - `minimums` *(minimumMap, optional)*
+    - `modularity` *(integer, optional, minimum: 0, maximum: 10000)*
+    - `acyclicity` *(integer, optional, minimum: 0, maximum: 10000)*
+    - `depth` *(integer, optional, minimum: 0, maximum: 10000)*
+    - `equality` *(integer, optional, minimum: 0, maximum: 10000)*
+    - `redundancy` *(integer, optional, minimum: 0, maximum: 10000)*
+  - `optimization` *(object, optional)*
+    - `mode` *(string, optional, enum: `off`, `bounded`)*
+    - `maxExtraEvaluations` *(integer, optional, minimum: 0, maximum: 2)*
+    - `minGainPoints` *(integer, optional, minimum: 1, maximum: 10000)*
 - `verification` *(object, optional)*
   - `checkers` *(array<object>, required)*
     - `checkId` *(string, required, minLength: 1)*
@@ -926,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)*
@@ -941,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 -->
@@ -1075,3 +1113,107 @@ back-reference itself from the execution receipt.
 Optional external signing-provider bundle. Its presence is not proof of a
 valid signature; verification must be performed by the configured signing
 provider with the requested identity and issuer policy.
+
+### 2.32 `task-state/<taskKey>/structural-quality/`
+
+<!-- forgeloop-doc: schema=structural-quality artifact=.forgeloop/task-state/<task-key>/structural-quality/baseline.json -->
+
+Task-owned provider-neutral structural-quality evidence. The directory contains
+one immutable `baseline.json` and zero or more typed evaluations under
+`evaluations/cycle-<cycle>-attempt-<attempt>.json`. There is deliberately no
+`latest.json`; readers derive the latest evaluation by numeric cycle and
+attempt ordering.
+
+The baseline is captured before execution and cannot be replaced after
+`EXECUTING` begins. Evaluations bind the current verification cycle to the
+baseline, contract, route, policy, scope, provider identity, and persisted
+check projection. Portable bundles include the evidence needed for audit and
+validate it without starting the provider.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:structural-quality -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `role` *(string, required, enum: `BASELINE`, `EVALUATION`)*
+- `taskId` *(string, required, minLength: 1)*
+- `capturedAt` *(string, required, minLength: 1)*
+- `verificationCycle` *(integer or null, required)*
+- `attempt` *(integer, required, minimum: 1)*
+- `status` *(string, required, enum: `PASS`, `FAIL`, `BLOCKED`, `NOT_OBSERVED`)*
+- `reasonCodes` *(array<string>, required)*
+- `errorCode` *(string or null, optional)*
+- `baselineSignal` *(integer or null, optional)*
+- `currentSignal` *(integer or null, optional)*
+- `bindings` *(object, required)*
+  - `contractFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `routeFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `policyFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `scopeFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `baselineFingerprint` *(string or null, optional)*
+  - `sourceMaterialFingerprint` *(string or null, optional)*
+  - `stateRevision` *(integer, optional, minimum: 0)*
+- `sourceObservation` *(object, optional)*
+  - `beforeFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `afterFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `stable` *(boolean, required)*
+- `provider` *(object, required)*
+  - `id` *(string, required, minLength: 1)*
+  - `version` *(string or null, required)*
+  - `transport` *(string, required, minLength: 1)*
+  - `executionMode` *(string, required, minLength: 1)*
+  - `measurementModel` *(string, optional, minLength: 1)*
+  - `compatibilityKey` *(string or null, optional)*
+- `detection` *(object, optional)*
+  - `available` *(boolean, required)*
+  - `providerId` *(string, required, minLength: 1)*
+  - `providerVersion` *(string or null, optional)*
+  - `transport` *(string, required, minLength: 1)*
+  - `measurementModel` *(string, optional, minLength: 1)*
+  - `compatibilityKey` *(string or null, optional)*
+  - `reasonCode` *(string or null, required)*
+- `scope` *(object, required)*
+  - `kind` *(string, required, const: `PROJECT`)*
+  - `projectRoot` *(string, required, const: `.`)*
+  - `providerConfigFingerprint` *(string or null, optional)*
+  - `architectureRulesFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `snapshot` *(snapshot, optional)*
+  - `qualitySignal` *(integer, required, minimum: 0, maximum: 10000)*
+  - `bottleneck` *(string, required, enum: `modularity`, `acyclicity`, `depth`, `equality`, `redundancy`)*
+  - `rootCauses` *(object, required)*
+    - `modularity` *(rootCause, required)*
+      - `score` *(integer, required, minimum: 0, maximum: 10000)*
+      - `raw` *(number, required)*
+    - `acyclicity` *(rootCause, required)*
+      - `score` *(integer, required, minimum: 0, maximum: 10000)*
+      - `raw` *(number, required)*
+    - `depth` *(rootCause, required)*
+      - `score` *(integer, required, minimum: 0, maximum: 10000)*
+      - `raw` *(number, required)*
+    - `equality` *(rootCause, required)*
+      - `score` *(integer, required, minimum: 0, maximum: 10000)*
+      - `raw` *(number, required)*
+    - `redundancy` *(rootCause, required)*
+      - `score` *(integer, required, minimum: 0, maximum: 10000)*
+      - `raw` *(number, required)*
+  - `statistics` *(object, required)*
+    - `files` *(integer or null, required)*
+    - `lines` *(integer or null, required)*
+    - `importEdges` *(integer or null, required)*
+    - `crossModuleEdges` *(integer or null, required)*
+  - `diagnostics` *(object or null, required)*
+- `comparison` *(comparison, optional)*
+  - `comparable` *(boolean, required)*
+  - `qualityDelta` *(integer or null, required)*
+  - `rootCauseDeltas` *(object, required)*
+  - `failedConditions` *(array<string>, optional)*
+  - `status` *(string, required, enum: `PASS`, `FAIL`, `BLOCKED`, `NOT_OBSERVED`)*
+  - `reasonCodes` *(array<string>, required)*
+
+<!-- END FORGELOOP GENERATED: schema:structural-quality -->
+
+For `BASELINE` artifacts and `PASS`/`FAIL` evaluations, `sourceMaterialFingerprint`
+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.

package/docs/CLI_REFERENCE.md

@@ -61,11 +61,12 @@ error codes. Default output and default JSON remain unchanged.
 | **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
+| **Verification & Completion** | [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
-| **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
 | **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**:
@@ -1235,6 +1275,89 @@ Evaluates task progress across verification cycles and detects stalls determinis
 
 ## 5. Completion & Reporting
 
+### `quality-baseline`
+
+Captures the provider observation that becomes the task's structural-quality
+baseline.
+
+- **Purpose**: Persist an immutable, task-bound structural-quality baseline before execution.
+- **When to use**: After a valid preflight checkpoint in `PLANNED`, before entering `EXECUTING`.
+- **Mutation**: Executes the configured provider, writes `baseline.json`, and appends a quality-baseline ledger event.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:quality-baseline: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)
+- `--replace`: replace a different baseline before EXECUTING
+- `--timeout-ms <number>`: bounded analyzer timeout in milliseconds
+- `--json`: emit baseline result as JSON
+
+<!-- END FORGELOOP GENERATED: cli:quality-baseline:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop quality-baseline --task task-001 --json
+  ```
+
+Use `--replace` only for an intentional pre-execution baseline replacement.
+The superseded fingerprint remains in the append-only ledger. The command
+does not accept an executable path, shell fragment, arbitrary arguments, score,
+or baseline value.
+
+### `quality-verify`
+
+Scans the current project through the configured structural-quality provider and
+compares it with the task baseline.
+
+- **Purpose**: Record a current-cycle structural-quality evaluation and project it into the canonical `structural-quality` check.
+- **When to use**: In `VERIFYING`, before `REVIEWING`.
+- **Mutation**: Executes the configured provider, writes a typed evaluation, and records the bound check/evidence projection.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:quality-verify: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)
+- `--timeout-ms <number>`: bounded analyzer timeout in milliseconds
+- `--json`: emit structural-quality verification as JSON
+
+<!-- END FORGELOOP GENERATED: cli:quality-verify:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop quality-verify --task task-001 --json
+  ```
+
+`PASS`, `FAIL`, `BLOCKED`, and `NOT_OBSERVED` remain distinct. A failed,
+unavailable, malformed, timed-out, truncated, stale, or incomparable provider
+result cannot become a passing check.
+
+### `quality-status`
+
+Projects the persisted structural-quality evidence without launching a provider.
+
+- **Purpose**: Inspect baseline, current-cycle status, policy comparison, and next guidance.
+- **When to use**: At any point when a read-only quality projection is needed.
+- **Mutation**: Read-only; it creates no provider process and writes no quality artifact.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:quality-status: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)
+- `--json`: emit persisted structural-quality status as JSON
+
+<!-- END FORGELOOP GENERATED: cli:quality-status:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop quality-status --task task-001 --json
+  ```
+
 ### `prepare-completion`
 
 Initializes or refreshes `.forgeloop/task-state/<taskKey>/execution-receipt.json`.

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

@@ -0,0 +1,171 @@
+# Knowledge sources and provenance
+
+Snapshot date: 2026-09-01
+Task: `luna-knowledge-pr-correction-20260901-v2`
+Target: ForgeLoop 1.8.0 at current `main` state at review start
+(`a4360ac9b24b19c74171fdbac3163b892d896484`, tag `v1.8.0`)
+
+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`
+Availability: task-local specification; not redistributed
+Snapshot date: 2026-08-31
+Revision/commit: not applicable
+License observed: not applicable; user-provided task specification
+Role: specification and curation boundary
+
+Accepted concepts:
+
+- candidate → coverage → proven gap → canonical home → minimal change →
+  proportional verification;
+- explicit context-cost, change-class, licensing, and fail-closed decisions;
+- execution-profile, provenance, lifecycle, and publication distinctions.
+
+Skipped concepts:
+
+- none of the plan's instructions were treated as external source material;
+  they define this task's scope and acceptance criteria.
+
+Canonical homes:
+
+- `docs/KNOWLEDGE_INTEGRATION_GAP_ANALYSIS.md` for decisions;
+- `docs/KNOWLEDGE_SOURCES.md` for provenance;
+- existing `ENG/` and protocol documents for operational rules.
+
+Reuse notes:
+
+- The attachment was used as a specification, not copied into a guide.
+
+## Learn UI
+
+URL: [https://learn-ui.com/](https://learn-ui.com/) and the Markdown index at
+[https://learn-ui.com/llms.txt](https://learn-ui.com/llms.txt)
+Snapshot date: 2026-08-31
+Revision/commit: not exposed by the inspected site
+License observed: no reuse license was identified in the inspected index and
+pages; reuse was therefore not assumed
+Role: discovery and research-only
+
+Accepted concepts:
+
+- prompts to check focus lifecycle, semantic representation, component states,
+  feedback, reduced motion, responsive behavior, and perceived performance;
+- independent, generalized guide refinements recorded in the gap matrix and
+  canonical accessibility/design guides.
+
+Skipped concepts:
+
+- source wording, examples, code, illustrations, page-specific constants,
+  visual recipes, and any source-exclusive taxonomy;
+- any claim that the site supplies a license or authorizes redistribution.
+
+Canonical homes:
+
+- `ENG/accessibility-eng.md` for objective keyboard, focus, semantic, and
+  status guidance;
+- `ENG/design-code-eng.md` for contextual component-state guidance;
+- existing performance and testing guides where equivalent coverage already
+  exists.
+
+Reuse notes:
+
+- No Learn UI text, code, example, image, or diagram was vendored.
+- The accepted wording was written from the concrete ForgeLoop gap and
+  corroborated with primary W3C/WAI/APG material where it became objective.
+
+## System Design Academy
+
+URL: [https://github.com/systemdesign42/system-design-academy](https://github.com/systemdesign42/system-design-academy)
+Snapshot date: 2026-08-31
+Revision/commit: `62cca085d6f5d7df1cfaf72c81f7304be9b9386e` (`main` at snapshot)
+License observed: `CC BY-NC-ND 4.0`, as declared by the repository license
+Role: discovery-only
+
+Accepted concepts:
+
+- broad topic discovery for context engineering, state/recovery, evaluation,
+  retries/idempotency, and distributed-system boundaries;
+- a prompt to verify each topic against ForgeLoop's existing canonical home.
+
+Skipped concepts:
+
+- all source-specific articles, prose, examples, diagrams, taxonomies, and
+  adaptations;
+- new protocol, router, profile, schema, evidence, or orchestration behavior;
+- a parallel knowledge library or technology-specific guide.
+
+Canonical homes:
+
+- existing `LOOP_SYSTEM_DESIGN.md`, `EXECUTION_STATE.md`,
+  `PROTOCOL_INTEGRATION.md`, `GUIDE_ROUTER.md`, `QUALITY_SCORECARD.md`,
+  `docs/EXECUTION_PROFILE_BENCHMARKS.md`, and current `ENG/` guides.
+
+Reuse notes:
+
+- This repository was used only to discover generic candidate topics.
+- Nothing from the repository was copied, translated, closely paraphrased,
+  diagrammed, or adapted.
+
+## W3C, WAI, and WAI-ARIA APG
+
+URLs: [WCAG 2.2](https://www.w3.org/TR/WCAG22/), [APG](https://www.w3.org/WAI/ARIA/apg/),
+[keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/),
+[dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/),
+[focus visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html),
+[reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html),
+[animation from interactions](https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html),
+and [status technique](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA22.html)
+Snapshot date: 2026-08-31
+Revision/commit: current web pages; no repository revision used
+License observed: primary standards/reference pages; no source text was
+reproduced
+Role: normative corroboration
+
+Accepted concepts:
+
+- keyboard operation and focus order;
+- focus visibility, dialog focus management, reflow, reduced-motion, and
+  status-announcement boundaries;
+- the distinction between automated checks and human assistive-technology
+  evaluation.
+
+Skipped concepts:
+
+- copying normative prose or presenting guide checks as certification;
+- claims of legal compliance, conformance, or human testing without scoped
+  evidence.
+
+Canonical homes:
+
+- `ENG/accessibility-eng.md` for implementation guidance;
+- `ENG/test-code-eng.md` for the automation-plus-human verification boundary.
+
+Reuse notes:
+
+- Links are retained for corroboration; no standards text, test result, or
+  certification claim is embedded.
+
+## Cross-source reuse boundary
+
+- No source text, source code, source examples, diagrams, or images are stored
+  in this repository as a result of this review.
+- External ideas remain research inputs until independently abstracted,
+  mapped to a current canonical home, and supported by a proven operational
+  gap.
+- Subjective judgments such as “premium,” “polished,” or “sophisticated” stay
+  advisory and cannot become completion evidence.
+- Licensing status is recorded only as observed at the snapshot; it is not
+  inferred, upgraded, or used as permission to redistribute material.