@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/docs/TROUBLESHOOTING.md

@@ -29,6 +29,10 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Responsibility contract rejects a pass](#symptom-responsibility-contract-rejects-a-pass)
 - [Verification scope is stale or unresolved](#symptom-verification-scope-is-stale-or-unresolved)
 - [Attestation or revision coverage is invalid](#symptom-attestation-or-revision-coverage-is-invalid)
+- [Structural-quality evidence is missing or blocked](#symptom-structural-quality-evidence-is-missing-or-blocked)
+- [Structural-quality verification reports a regression](#symptom-structural-quality-verification-reports-a-regression)
+- [Structural-quality provider is unavailable or invalid](#symptom-structural-quality-provider-is-unavailable-or-invalid)
+- [Structural-quality evidence is stale or incomparable](#symptom-structural-quality-evidence-is-stale-or-incomparable)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
 - [Task claim conflict or recovered task](#symptom-task-creation-blocked-by-a-write-claim-conflict-e_task_scope_conflict)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
@@ -757,16 +761,50 @@ explicit operation only when the task's scope permits it.
 
 ---
 
+### Symptom: Advisory Context Recall Is Unavailable or Rejected
+
+#### Error Codes: `E_ADVISORY_CONTEXT_PROVIDER_INVALID`, `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE`, `E_ADVISORY_CONTEXT_QUERY_INVALID`, `E_ADVISORY_CONTEXT_REQUEST_INVALID`, `E_ADVISORY_CONTEXT_RESULT_INVALID`, `E_ADVISORY_CONTEXT_TIMEOUT`, `E_ADVISORY_CONTEXT_OUTPUT_LIMIT`, `E_PORTABLE_CONTEXT_INVALID`
+
+#### What it means
+
+The host's optional advisory provider is missing, malformed, unavailable, too
+slow, or returned content outside the bounded portable-context contract. These
+failures never become lifecycle, evidence, completion, or next-action failures.
+
+#### Safe recovery
+
+Inspect provider registration and normalize the request before retrying through
+the Integration API. Reduce query, item, total-output, and timeout values to the
+documented budgets, remove secrets/control characters, and ensure the provider
+returns only allowlisted item fields. If advisory context is unavailable,
+continue from canonical task state; do not fabricate a provider or execute its
+text.
+
+### Symptom: Continuity Lint Reports a Contradictory Hint
+
+Continuity lint is diagnostic only. Its findings do not change reconciliation,
+state, evidence, authority, or completion:
+
+| Finding | Meaning | Safe response |
+| --- | --- | --- |
+| `CONTINUITY_REMAINING_ALREADY_COMPLETED` | A remaining-work item is already recorded as completed. | Refresh the operational note; do not change canonical completion evidence. |
+| `CONTINUITY_FOCUS_ALREADY_COMPLETED` | The current focus ID is already completed. | Choose a current inspection focus or clear the hint. |
+| `CONTINUITY_ITEM_ROLE_CONFLICT` | An item appears in both remaining work and known issues. | Remove the contradictory hint through `record-continuity`. |
+| `CONTINUITY_INSPECT_PATH_MISSING` | An `inspectFirst` path is not present in the current target. | Reconcile the checkout and update the path hint. |
+| `CONTINUITY_EMPTY_HINT_SET` | No operational hint was supplied. | Treat the result as informational and follow canonical `next`. |
+
 ### Symptom: Handoff Is Invalid or Tampered
 
-#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`
+#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`, `E_HANDOFF_STALE`, `E_HANDOFF_ALREADY_ACCEPTED`, `E_HANDOFF_ACCEPTANCE_INCONSISTENT`
 
 #### What it means
 
 The immutable handoff envelope is malformed, its state is unavailable, its
 digest no longer matches, or the requested snapshot does not exist. A handoff
 note is not delegation, authority, independent review evidence, or completion
-evidence.
+evidence. Acceptance is exactly-once operational receipt only. The current
+repository branch and HEAD are checked directly, so clean committed checkout
+drift can make a handoff stale even when changed paths are empty.
 
 #### Safe recovery
 
@@ -777,6 +815,12 @@ forgeloop continuity --task <id> --json
 forgeloop reconcile-continuity --task <id> --json
 ```
 
+If `handoff-list` or `handoff-show` reports `INCONSISTENT`, inspect the
+`reasonCodes` field. The commands validate the event ledger before projecting
+acceptance and never turn an unreadable or invalid ledger into an empty ledger.
+Repair the named ledger through the canonical protocol workflow; do not edit
+`events.ndjson` by hand.
+
 Use the last valid handoff or continuity only to focus inspection, then trust
 the canonical task state and checkout. Never repair a handoff by editing or
 deleting its JSON file.
@@ -890,6 +934,88 @@ forgeloop next --task <id> --json
 
 ---
 
+### Symptom: Structural-quality evidence is missing or blocked
+
+#### Error Codes: `E_STRUCTURAL_QUALITY_BASELINE_MISSING`, `E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID`, `E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE`
+
+This applies when structural quality is configured in `gate` mode but a valid
+baseline or current provider observation is unavailable. `preflight` can be
+ready before the baseline exists, but `PLANNED` cannot enter `EXECUTING` until
+the baseline is captured. A missing provider is a visible limitation in
+`observe` mode and a blocker in `gate` mode.
+
+Inspect the persisted projection without launching a provider:
+
+```bash
+forgeloop quality-status --task <id> --json
+forgeloop next --task <id> --json
+```
+
+Capture the baseline only in `PLANNED` after a valid preflight:
+
+```bash
+forgeloop quality-baseline --task <id> --json
+```
+
+Do not replace a baseline after execution begins. Install or upgrade Sentrux
+only through a separately authorized, user-managed process.
+
+### Symptom: Structural-quality verification reports a regression
+
+#### Error Code: `E_STRUCTURAL_QUALITY_REGRESSION`
+
+The current observation violated the configured aggregate, dimension, cycle, or
+minimum policy. An improving aggregate can still fail when a dimension budget
+or cycle rule fails. Inspect the evidence and follow the normal diagnosis and
+correction lifecycle. Use the evaluation artifact reference returned by
+`quality-verify` as evidence when recording the diagnosis.
+
+```bash
+forgeloop quality-status --task <id> --json
+forgeloop next --task <id> --json
+```
+
+The evaluation's bottleneck, root-cause deltas, failed conditions, and artifact
+reference are evidence. ForgeLoop does not auto-create a diagnosis and does not
+accept a repeated hypothesis without new information.
+
+### Symptom: Structural-quality provider is unavailable or invalid
+
+#### Error Codes: `E_STRUCTURAL_QUALITY_PROVIDER_INVALID`, `E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED`, `E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID`, `E_STRUCTURAL_QUALITY_SCAN_FAILED`, `E_STRUCTURAL_QUALITY_TIMEOUT`, `E_STRUCTURAL_QUALITY_OUTPUT_LIMIT`
+
+The provider boundary failed closed because detection, version, MCP protocol,
+scan, timeout, or output limits were not satisfied. Raw MCP streams are never
+persisted and partial provider output is never a passing observation.
+
+Use the configured mode's semantics: `observe` records `NOT_OBSERVED`, while
+`gate` records `BLOCKED` and keeps completion unavailable. Check the provider's
+own installation and logs, then rerun the same ForgeLoop command after the
+cause is understood. The project configuration cannot select an executable,
+shell, arbitrary arguments, or a score override.
+
+### Symptom: Structural-quality evidence is stale or incomparable
+
+#### Error Codes: `E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH`, `E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE`, `E_STRUCTURAL_QUALITY_EVIDENCE_STALE`, `E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE`
+
+The baseline and current evaluation no longer describe the same task inputs.
+Provider ID or version, policy, route, contract, scan scope, or
+`.sentrux/rules.toml` drift makes the comparison incomparable. A prior-cycle
+pass cannot satisfy a current-cycle gate. If source material cannot be read
+or contains an unsafe symlink, ForgeLoop returns
+`E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE` and does not persist a
+passing observation.
+
+Inspect the bound artifacts and current projection:
+
+```bash
+forgeloop quality-status --task <id> --json
+forgeloop audit --task <id> --json
+```
+
+Resolve the legitimate drift through the normal task lifecycle. Do not edit a
+baseline or evaluation by hand, and do not use a bundle as a reason to bypass
+current-cycle validation.
+
 ## Stable Error and Reason Codes
 
 <!-- BEGIN FORGELOOP GENERATED: public-error-codes -->
@@ -916,6 +1042,13 @@ forgeloop next --task <id> --json
 | `E_ACTION_STATE_MISMATCH` | Requested durable action transition is not part of the canonical state machine. | Inspect current action state with forgeloop action-show and use a legal transition; never edit action artifacts by hand. |
 | `E_ACTION_VERIFICATION_INVALID` | Verification evidence does not resolve to a canonical passed ForgeLoop artifact bound to this task and action. | Supply a canonical execution or check reference produced by run-check for this task; arbitrary strings fail closed. |
 | `E_ACTION_VERIFICATION_REQUIRED` | The action cannot reach VERIFIED through this surface; canonical independent postcondition evidence is required. | Run an independent verification check, then record it with forgeloop action-verify; exit code 0 alone is not verification. |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | Advisory context output exceeded the configured character or item limit. | Reduce query scope, limit items, or truncate oversized summaries at the provider. |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` | Advisory context provider configuration or interface implementation is invalid. | Use a provider implementing id, recall(input) with bounded query parameters; advisory context is optional. |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | Requested advisory context provider is not registered in runtime context. | Register the provider in runtime context before recall, or proceed without advisory context; provider failure never blocks canonical lifecycle. |
+| `E_ADVISORY_CONTEXT_QUERY_INVALID` | Advisory context query failed portable-context validation or exceeded budget. | Provide a bounded query free of control characters and secret-like values. |
+| `E_ADVISORY_CONTEXT_REQUEST_INVALID` | Advisory context recall budgets are not finite integer values within the supported request contract. | Provide finite integer limit, maxItemChars, maxTotalChars, and timeoutMs values; oversized valid values are clamped to documented maxima. |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | Advisory context provider returned an invalid result structure. | Ensure provider returns items with string summary and optional title, sourceRef, observedAt, confidence. |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Advisory context recall exceeded its execution timeout. | Use a responsive provider or increase timeout within limits; advisory context is optional. |
 | `E_APPROVAL_ALREADY_RESOLVED` | Approval is one-time resolvable and has already been approved or rejected. | Request a new approval if another decision is required. |
 | `E_APPROVAL_INVALID` | Approval artifact is malformed or does not bind the required fingerprint tuple. | Request a new approval with forgeloop approval-request; never hand-edit approval artifacts. |
 | `E_APPROVAL_STALE` | Approval no longer matches the current action fingerprint, contract fingerprint, task revision, or capability. | Request and resolve a fresh approval against the current action revision. |
@@ -1004,8 +1137,12 @@ forgeloop next --task <id> --json
 | `E_GATE_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_GATE_STALE` | Referenced gate artifact changed after approval. | Update artifact SHA-256 in gate file. |
 | `E_GATE_UNVERIFIED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_HANDOFF_ACCEPTANCE_INCONSISTENT` | Handoff acceptance disagrees with task event ledger history. | Verify ledger integrity and require a preceding valid HANDOFF_CREATED event. |
+| `E_HANDOFF_ACCEPTANCE_UNBOUND` | Handoff snapshot lacks required workStateFingerprint binding. | Create a fresh handoff from the current ForgeLoop version before accepting it. |
+| `E_HANDOFF_ALREADY_ACCEPTED` | Handoff was already accepted by a different consumer. | Create a new handoff for the new consumer; do not manually edit acceptance events. |
 | `E_HANDOFF_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HANDOFF_NOT_FOUND` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_HANDOFF_STALE` | Handoff snapshot has drifted from the current canonical task state or repository. | Create a new fresh handoff from the current task state instead of accepting a stale snapshot. |
 | `E_HANDOFF_STATE_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HANDOFF_TAMPERED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID` | Hypothesis disposition evidence references do not resolve to checks of the active cycle. | Reference at least one check ID recorded in the active verification cycle. |
@@ -1038,6 +1175,7 @@ forgeloop next --task <id> --json
 | `E_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
 | `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
 | `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
+| `E_PORTABLE_CONTEXT_INVALID` | Text or object failed portable-context safety, character, or secret limits. | Ensure text is bounded, contains no control characters, and contains no secret-like values. |
 | `E_PREFLIGHT_EVENT_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PREFLIGHT_GATES_STALE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PREFLIGHT_GATE_EVENT_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1090,6 +1228,27 @@ forgeloop next --task <id> --json
 | `E_STATE_REVALIDATION_REQUIRED` | The work-state checkpoint must be revalidated before the lifecycle can continue. | Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift. |
 | `E_STATE_TASK_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_STRATEGY_OSCILLATION` | Correction history oscillates between previously exhausted strategies without new information. | Gather a genuinely new observation or test a materially different falsifiable hypothesis. |
+| `E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Reconcile contract, route, policy, scope, provider, or rules drift before using the baseline. |
+| `E_STRUCTURAL_QUALITY_BASELINE_EXISTS` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use the existing immutable baseline or request --replace while the task is still before EXECUTING. |
+| `E_STRUCTURAL_QUALITY_BASELINE_MISSING` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Run forgeloop quality-baseline --task <id> after PLANNED and before EXECUTING. |
+| `E_STRUCTURAL_QUALITY_BASELINE_PHASE_INVALID` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Baseline replacement is forbidden after EXECUTING; repair the current task against its original baseline. |
+| `E_STRUCTURAL_QUALITY_CONFIGURATION_INVALID` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Correct structuralQuality mode, provider ID, budgets, floors, or optimization limits in .forgeloop/config.json. |
+| `E_STRUCTURAL_QUALITY_EVALUATION_INCOMPARABLE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Restore the baseline provider/version/rules/policy/scope bindings and rerun quality-verify. |
+| `E_STRUCTURAL_QUALITY_EVIDENCE_STALE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Rerun quality-verify in the active verification cycle and refresh completion through the canonical receipt pipeline. |
+| `E_STRUCTURAL_QUALITY_MEASUREMENT_MODEL_MISMATCH` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a compatible measurement model and provider across baseline and evaluation observations. |
+| `E_STRUCTURAL_QUALITY_OBSERVATION_EPOCH_STALE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Rerun quality-verify under the active task epoch without concurrent state mutations. |
+| `E_STRUCTURAL_QUALITY_OUTPUT_LIMIT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Reduce provider output or diagnostics; the 2 MiB combined process-output limit is fail-closed. |
+| `E_STRUCTURAL_QUALITY_PROJECTION_INCOMPLETE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Rerun quality-verify to reconcile and project the canonical check from the existing evaluation artifact. |
+| `E_STRUCTURAL_QUALITY_PROVIDER_INVALID` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a provider implementing id, detect(input), and scan(input) with the documented normalized boundary. |
+| `E_STRUCTURAL_QUALITY_PROVIDER_PROTOCOL_INVALID` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Repair the provider MCP handshake or response shape; malformed external data cannot become evidence. |
+| `E_STRUCTURAL_QUALITY_PROVIDER_TOOL_CONTRACT_INVALID` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Ensure the provider exposes the required scan and health tool argument schemas. |
+| `E_STRUCTURAL_QUALITY_PROVIDER_UNAVAILABLE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Install or expose the requested provider outside ForgeLoop, or use observe mode and record the limitation; ForgeLoop never auto-installs it. |
+| `E_STRUCTURAL_QUALITY_PROVIDER_VERSION_UNSUPPORTED` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a verified Sentrux version (0.5.5, 0.5.6, or 0.5.7), or select a compatible provider through trusted runtime context. |
+| `E_STRUCTURAL_QUALITY_REGRESSION` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use the bottleneck and root-cause deltas to record an evidence-backed diagnosis, correct within scope, and verify a new cycle. |
+| `E_STRUCTURAL_QUALITY_SCAN_FAILED` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Inspect the provider failure and rerun quality-baseline or quality-verify after the external analyzer is healthy. |
+| `E_STRUCTURAL_QUALITY_SOURCE_DRIFT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Ensure the worktree is not mutated during provider observation and rerun quality-baseline or quality-verify. |
+| `E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Repair unreadable or unsafe source material before structural-quality evidence can be trusted. |
+| `E_STRUCTURAL_QUALITY_TIMEOUT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a responsive provider or a bounded timeout within the supported limit; never promote a timed-out scan. |
 | `E_TASK_ALREADY_EXISTS` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_ALREADY_RECOVERED` | The task already has active durable recovered state. | Inspect the existing recovery metadata; use task-resume to reacquire claims or leave the task recovered. |
 | `E_TASK_AMBIGUOUS` | Multiple tasks exist in the project but no task selector was provided. | Select a task explicitly using --task <id> or FORGELOOP_TASK=<id>. |

package/docs/UNIVERSAL_INTEGRATION.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -51,10 +51,12 @@
     "docs/assets/diagrams",
     "docs/GETTING_STARTED.md",
     "docs/CROSS_HARNESS_CONTINUITY.md",
+    "docs/ADVISORY_CONTEXT.md",
     "docs/CLI_REFERENCE.md",
     "docs/ARTIFACT_REFERENCE.md",
     "docs/TROUBLESHOOTING.md",
     "docs/RECIPES.md",
+    "docs/STRUCTURAL_QUALITY.md",
     "docs/DOCUMENTATION_GUIDE.md",
     "docs/RELEASE_CHECKLIST.md",
     "scripts/CI_VALIDATORS.md",
@@ -68,6 +70,7 @@
     "docs/PLATFORM_ADAPTERS.md",
     "docs/AGENT_PROTOCOL_SUMMARY.md",
     "docs/EXECUTION_PROFILE_BENCHMARKS.md",
+    "docs/KNOWLEDGE_SOURCES.md",
     "scripts/generate-shell-completions.mjs",
     "scripts/generate-agent-protocol-summary.mjs",
     "scripts/run-execution-profile-benchmarks.mjs",

package/schemas/config.schema.json

@@ -12,6 +12,28 @@
     "policy": { "type": "string", "minLength": 1 },
     "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "requiredEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "structuralQuality": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["off", "observe", "gate"] },
+        "provider": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$" },
+        "maxRegressionPoints": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "dimensionBudgets": { "$ref": "#/$defs/dimensionMap" },
+        "forbidNewCycles": { "type": "boolean" },
+        "minQualitySignal": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+        "minimums": { "$ref": "#/$defs/minimumMap" },
+        "optimization": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "enum": ["off", "bounded"] },
+            "maxExtraEvaluations": { "type": "integer", "minimum": 0, "maximum": 2 },
+            "minGainPoints": { "type": "integer", "minimum": 1, "maximum": 10000 }
+          }
+        }
+      }
+    },
     "verification": {
       "type": "object",
       "required": ["checkers"],
@@ -69,5 +91,29 @@
       }
     }
   },
+  "$defs": {
+    "dimensionMap": {
+      "type": "object",
+      "properties": {
+        "modularity": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+        "acyclicity": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+        "depth": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+        "equality": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+        "redundancy": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "minimumMap": {
+      "type": "object",
+      "properties": {
+        "modularity": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "acyclicity": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "depth": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "equality": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "redundancy": { "type": "integer", "minimum": 0, "maximum": 10000 }
+      },
+      "additionalProperties": false
+    }
+  },
   "additionalProperties": false
 }

package/schemas/handoff-envelope.schema.json

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

package/schemas/preflight.schema.json

@@ -17,7 +17,8 @@
     "errors": { "type": "array", "items": { "type": "object" } },
     "fingerprints": { "type": "object" },
     "sources": { "type": "object" },
-    "policy": { "type": "object" }
+    "policy": { "type": "object" },
+    "structuralQuality": { "type": "object" }
   },
   "additionalProperties": false
 }

package/schemas/structural-quality.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/structural-quality.schema.json",
+  "title": "ForgeLoop structural quality evidence",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "role", "taskId", "capturedAt", "verificationCycle", "attempt", "bindings", "provider", "scope", "status", "reasonCodes"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "role": { "enum": ["BASELINE", "EVALUATION"] },
+    "taskId": { "type": "string", "minLength": 1 },
+    "capturedAt": { "type": "string", "minLength": 1 },
+    "verificationCycle": { "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }] },
+    "attempt": { "type": "integer", "minimum": 1 },
+    "status": { "enum": ["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"] },
+    "reasonCodes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "errorCode": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "baselineSignal": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+    "currentSignal": { "oneOf": [{ "type": "integer", "minimum": 0, "maximum": 10000 }, { "type": "null" }] },
+    "bindings": {
+      "type": "object",
+      "required": ["contractFingerprint", "routeFingerprint", "policyFingerprint", "scopeFingerprint"],
+      "properties": {
+        "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "routeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "policyFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "scopeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "baselineFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "sourceMaterialFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "stateRevision": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "sourceObservation": {
+      "type": "object",
+      "required": ["beforeFingerprint", "afterFingerprint", "stable"],
+      "properties": {
+        "beforeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "afterFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "stable": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "provider": {
+      "type": "object",
+      "required": ["id", "version", "transport", "executionMode"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "transport": { "type": "string", "minLength": 1 },
+        "executionMode": { "type": "string", "minLength": 1 },
+        "measurementModel": { "type": "string", "minLength": 1 },
+        "compatibilityKey": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "detection": {
+      "type": "object",
+      "required": ["available", "providerId", "transport", "reasonCode"],
+      "properties": {
+        "available": { "type": "boolean" },
+        "providerId": { "type": "string", "minLength": 1 },
+        "providerVersion": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "transport": { "type": "string", "minLength": 1 },
+        "measurementModel": { "type": "string", "minLength": 1 },
+        "compatibilityKey": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "reasonCode": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "projectRoot"],
+      "properties": {
+        "kind": { "const": "PROJECT" },
+        "projectRoot": { "const": "." },
+        "providerConfigFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+        "architectureRulesFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "snapshot": { "$ref": "#/$defs/snapshot" },
+    "comparison": { "$ref": "#/$defs/comparison" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "rootCause": {
+      "type": "object",
+      "required": ["score", "raw"],
+      "properties": {
+        "score": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "raw": { "type": "number" }
+      },
+      "additionalProperties": false
+    },
+    "snapshot": {
+      "type": "object",
+      "required": ["qualitySignal", "bottleneck", "rootCauses", "statistics", "diagnostics"],
+      "properties": {
+        "qualitySignal": { "type": "integer", "minimum": 0, "maximum": 10000 },
+        "bottleneck": { "enum": ["modularity", "acyclicity", "depth", "equality", "redundancy"] },
+        "rootCauses": {
+          "type": "object",
+          "required": ["modularity", "acyclicity", "depth", "equality", "redundancy"],
+          "properties": {
+            "modularity": { "$ref": "#/$defs/rootCause" },
+            "acyclicity": { "$ref": "#/$defs/rootCause" },
+            "depth": { "$ref": "#/$defs/rootCause" },
+            "equality": { "$ref": "#/$defs/rootCause" },
+            "redundancy": { "$ref": "#/$defs/rootCause" }
+          },
+          "additionalProperties": false
+        },
+        "statistics": {
+          "type": "object",
+          "required": ["files", "lines", "importEdges", "crossModuleEdges"],
+          "properties": {
+            "files": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "lines": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "importEdges": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+            "crossModuleEdges": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }
+          },
+          "additionalProperties": false
+        },
+        "diagnostics": { "oneOf": [{ "type": "object" }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "comparison": {
+      "type": "object",
+      "required": ["comparable", "qualityDelta", "rootCauseDeltas", "status", "reasonCodes"],
+      "properties": {
+        "comparable": { "type": "boolean" },
+        "qualityDelta": { "oneOf": [{ "type": "integer" }, { "type": "null" }] },
+        "rootCauseDeltas": { "type": "object" },
+        "failedConditions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "status": { "enum": ["PASS", "FAIL", "BLOCKED", "NOT_OBSERVED"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "role": { "const": "BASELINE" } } },
+      "then": {
+        "required": ["sourceObservation"],
+        "properties": {
+          "bindings": {
+            "required": ["sourceMaterialFingerprint"],
+            "properties": {
+              "sourceMaterialFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          },
+          "sourceObservation": { "properties": { "stable": { "const": true } } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["PASS", "FAIL"] } } },
+      "then": {
+        "required": ["sourceObservation"],
+        "properties": {
+          "bindings": {
+            "required": ["sourceMaterialFingerprint"],
+            "properties": {
+              "sourceMaterialFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            }
+          },
+          "sourceObservation": { "properties": { "stable": { "const": true } } }
+        }
+      }
+    }
+  ]
+}

package/scripts/check-changelog-freshness.mjs

@@ -26,6 +26,26 @@ export function unreleasedSection(changelog) {
   return nextHeading ? rest.slice(0, nextHeading.index) : rest;
 }
 
+export function releaseSection(changelog) {
+  const heading = /^##[ \t]+(v?\d+\.\d+\.\d+)(?:[ \t]+-[^\r\n]*)?$/imu.exec(changelog);
+  if (!heading) return null;
+  const rest = changelog.slice(heading.index + heading[0].length);
+  const nextHeading = /^##\s/imu.exec(rest);
+  return {
+    version: heading[1].replace(/^v/u, ""),
+    section: nextHeading ? rest.slice(0, nextHeading.index) : rest,
+  };
+}
+
+function compareVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
 export function stripHtmlComments(value) {
   const chunks = [];
   let cursor = 0;
@@ -55,11 +75,15 @@ export function hasMeaningfulUnreleasedContent(section) {
 
 export function checkChangelogFreshness({ changelog, tags = [], commitsSinceLatestTag = 0, allowEmpty = false } = {}) {
   const latestTag = latestReleaseTag(tags);
-  const section = unreleasedSection(changelog);
+  const unreleased = unreleasedSection(changelog);
+  const pendingRelease = releaseSection(changelog);
+  const pendingReleaseIsNewer = pendingRelease &&
+    (!latestTag || compareVersions(pendingRelease.version, latestTag.replace(/^v/u, "")) > 0);
+  const section = unreleased || (pendingReleaseIsNewer ? pendingRelease.section : "");
   const hasChanges = commitsSinceLatestTag > 0;
   const populated = hasMeaningfulUnreleasedContent(section);
   const ok = allowEmpty || !hasChanges || populated;
-  return { ok, latestTag, hasChanges, populated, section };
+  return { ok, latestTag, hasChanges, populated, section, pendingRelease };
 }
 
 async function run() {
@@ -71,7 +95,7 @@ async function run() {
     : Number(git(["rev-list", "--count", "HEAD"]));
   const result = checkChangelogFreshness({ changelog, tags, commitsSinceLatestTag, allowEmpty: process.argv.includes("--allow-empty") });
   if (!result.ok) {
-    console.error(`CHANGELOG.md has changes since ${result.latestTag ?? "the initial commit"} but the Unreleased section is empty.`);
+    console.error(`CHANGELOG.md has changes since ${result.latestTag ?? "the initial commit"} but no populated Unreleased or pending release section exists.`);
     process.exitCode = 1;
     return;
   }