@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/.cursor/rules/project-loop.mdc

@@ -2,14 +2,11 @@
 description: Universal verified project loop
 alwaysApply: true
 ---
-
 <!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
 # Cursor — Universal Project Loop
-
 This project is ForgeLoop-enabled. If your execution environment loaded this
 file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
 Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
-
 1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../../PROTOCOL_INTEGRATION.md).
 2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize if in `template` mode.
 3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate relevant guides and report IDs.
@@ -24,6 +21,12 @@ After implementation work for the current task is complete, run `forgeloop next`
 
 10. Report only demonstrated results and checks.
 
+When `structuralQuality` is enabled, capture its baseline after planning and
+before `EXECUTING`, evaluate the current cycle in `VERIFYING`, and route
+regressions through the existing diagnosis/correction loop. Do not claim
+`PASS` for unavailable evidence, replace a baseline after execution begins, or
+expand scope to chase a perfect score.
+
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 

package/.github/copilot-instructions.md

@@ -21,6 +21,11 @@ Use these instructions across the repository while preserving local rules.
 After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 
 - Report results, checks actually run, limitations, and publication state.
+- When `structuralQuality` is enabled, capture its baseline after planning and
+  before `EXECUTING`, evaluate the current cycle in `VERIFYING`, and route
+  regressions through the existing diagnosis/correction loop. Never claim
+  `PASS` for unavailable evidence, replace a baseline after execution begins,
+  or expand scope to chase a perfect score.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.

package/AGENTS.md

@@ -20,6 +20,12 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 1. Finish with result, checks run, limitations, and publication state.
 
+When `structuralQuality` is enabled, capture its task-bound baseline after
+planning and before `EXECUTING`, record the current-cycle evaluation in
+`VERIFYING`, and route regressions through the existing diagnosis/correction
+loop. Never claim structural `PASS` for unavailable evidence, replace a
+baseline after execution begins, or widen scope to chase a perfect score.
+
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 

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

@@ -20,6 +20,12 @@ When working in this repository:
 1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 1. Report current evidence, limitations, and publication state without claiming checks that were not run.
 
+When `structuralQuality` is enabled, capture its baseline after planning and
+before `EXECUTING`, evaluate the current cycle in `VERIFYING`, and use the
+existing diagnosis/correction lifecycle for regressions. Do not report
+unavailable evidence as `PASS`, replace a baseline after execution begins, or
+expand scope to pursue a perfect score.
+
 Do not stop for non-blocking missing product details. When a safe, reversible
 local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 

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,22 +15,27 @@ 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/` |
 | Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
 | Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
 | Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| 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 |
 | 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 |
@@ -66,6 +71,7 @@ integration and guide context. Use this map before editing documentation.
 | **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
+| **Configuring structural quality feedback** | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) |
 | **Understanding verification trust** | [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md#differential-verification-scope) |
 | **Understanding attestation trust** | [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md#trust-levels) |
 | **Maintaining generated diagrams** | [`docs/diagrams/README.md`](./docs/diagrams/README.md) |
@@ -87,6 +93,7 @@ integration and guide context. Use this map before editing documentation.
 - **Fix a blocked, stale, or invalid state**: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
 - **Recover a stale task or reacquire released claims**: [`docs/RECIPES.md`](./docs/RECIPES.md#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
 - **Find operational copy-paste commands**: [`docs/RECIPES.md`](./docs/RECIPES.md)
+- **Measure structural quality without replacing tests**: [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md)
 - **Read the normative protocol specification**: [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **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)

package/ENG/accessibility-eng.md

@@ -3,7 +3,7 @@ name: accessibility-eng
 language: en
 description: "Practical WCAG 2.2-oriented accessibility protocol for web, mobile, and desktop."
 version: "2026.09"
-last-reviewed: "2026-08-10"
+last-reviewed: "2026-08-31"
 guide-id: accessibility
 completion-evidence:
   - keyboard-navigation
@@ -77,6 +77,8 @@ To ensure technical integrity, any AI interacting with the project **MUST**:
 - **Keyboard (SC 2.1.1):** all functionality **MUST** be operable without a mouse. Where the function depends on the path of movement rather than only its endpoints, document why the WCAG exception applies and provide a practical alternative when possible. Avoid purely pointer-based listeners without keyboard event equivalents (`onKeyDown`).
 - **Focus (SC 2.4.7, 2.4.11):** focus **MUST** be visible, never entirely obscured by author content (e.g., sticky headers/footers), persistent, and never suppressed via CSS (`outline: none` without fallback is forbidden).
 - **SPA routing:** after client-side routing changes, focus **MUST** be managed and properly reset (e.g., sending focus to the top or an `h1`). Avoid lost focus on the screen.
+- **Focus order and lifecycle (SC 2.4.3):** the sequential keyboard path **MUST** preserve meaning and operability. Prefer alignment between DOM order, reading order, and visual order when divergence would create confusing or illogical navigation. Avoid positive `tabindex` as a ForgeLoop accessibility best practice; repair the document structure whenever practical. When content is inserted, removed, expanded, collapsed, replaced, or routed, define the next logical focus destination and do not leave focus on a removed or unavailable node.
+- **Modal dialog focus contract:** for a modal dialog, choose the initial focus target according to the modal task, move focus inside the modal, keep the inactive background out of the keyboard path, and remember the invoking control. On close, return focus to that control only when it still exists and is available; otherwise move focus to a documented logical fallback, such as the control that owns the resulting content or the newly exposed heading. A trigger removed during the operation is a lifecycle case, not permission to drop focus. Do not apply modal containment rules to non-modal dialogs.
 - **Targets (SC 2.5.8):** interactive elements MUST have a minimum size of **24×24 CSS pixels** — the WCAG 2.2 AA floor — except when an equivalent larger target exists, sufficient spacing prevents accidental activation, or the target sits inline in text.
   **House Rule†:** design to **44×44px** (48×48 under Shield), the ergonomic floor shared by Apple HIG and Material Design. Under Shield, 44×44 is normative (SC 2.5.5 AAA).
 - **Dragging (SC 2.5.7, AA):** all functionality operated by dragging MUST have a simple pointer alternative that does not require dragging, unless dragging is essential or the behavior is provided by the user agent and has not been modified by the author. The alternative cannot rely only on a path-based gesture.
@@ -96,6 +98,12 @@ To ensure technical integrity, any AI interacting with the project **MUST**:
 - **Semantic HTML:** **MUST** prefer native (HTML5) elements over custom ones.
 - **Interoperability:** the code **MUST** be compatible with current assistive technologies (ISO 9241-171).
 
+### Composite visuals, code, and status
+
+- When several DOM nodes together communicate one informative visual, expose one meaningful semantic representation and keep decorative fragments out of the accessibility tree. Do not make users traverse borders, connector lines, repeated labels, or illustration layers that add no information.
+- A code example **MUST** remain available as text with code semantics. Line-number gutters, syntax decoration, and duplicate visual labels **SHOULD** be hidden from assistive technology when they do not add meaning. A copy or expand action **MUST** be a named, keyboard-operable control; its result belongs in the pre-mounted status region described above rather than only in a changed icon or color.
+- A composite presentation is not evidence that its semantics work. Verify the accessible name, role, value, focus path, and status announcement in the supported browser and assistive-technology combinations; automated tree checks cover only part of this behavior.
+
 ## 4. Visual directives (strict UI criteria)
 
 These directives combine WCAG requirements where identified and this guide's ergonomic recommendations. They support implementation but do not assure certification or legal compliance.
@@ -120,7 +128,7 @@ When identifying an unmapped or highly complex component (e.g., charts, dynamic
 - **Leaked focus traps:** **MUST NOT** create modals without managing focus. When a modal is open:
   - focus MUST move into the modal;
   - focus MUST be trapped within the modal;
-  - focus MUST return to the triggering element when closed;
+  - focus MUST return to the triggering element when it still exists and remains available; otherwise focus MUST move to a documented logical fallback;
   - background content MUST NOT be interactive or reachable via keyboard.
 - **Placeholder labels:** **MUST NOT** use `placeholder` as the sole form of label. Crucial instructions (like date formats) **MUST** be visible outside the field to prevent disappearance during filling.
 - **ARIA soup:** **MUST NOT** add ARIA where native HTML already provides the semantics — no ARIA is better than bad ARIA. Forbidden by default: redundant roles (`role="button"` on a `<button>`), `aria-label` duplicating visible text (harmless today, but it drifts into an SC 2.5.3 failure when the text changes), and static ARIA states that are never updated (hardcoded `aria-expanded` — an SC 4.1.2 failure). ARIA is the fallback for gaps in native semantics ([First Rule of ARIA Use](https://www.w3.org/TR/using-aria/#rule1)), not a seasoning. The number of ARIA attributes is not evidence of accessibility; validate behavior, semantics, and assistive-technology support.
@@ -131,12 +139,14 @@ When identifying an unmapped or highly complex component (e.g., charts, dynamic
 
 - [ ] **Technical check:** run the project's already configured static accessibility checks and engines such as `Axe` where applicable (see [`test-code-eng.md`](./test-code-eng.md) for tool selection). Do not install a tool solely to satisfy this item; record a required unavailable check as blocked.
 - [ ] **Tab order:** `Tab` key path manually validated (ensures absence of frontend dead-ends).
+- [ ] **Focus order and lifecycle:** sequential order preserves meaning and operability; DOM, reading, and visual order are aligned where divergence would create confusing or illogical navigation; no positive `tabindex` is used; inserted, removed, expanded, collapsed, replaced, and routed content has a defined logical focus destination; modal dialogs have intentional initial focus and a valid return or fallback target.
 - [ ] **Focus (SC 2.4.13, AAA when applicable):** measure the area equivalent to a 2 CSS pixel perimeter and 3:1 contrast between the same pixels in focused and unfocused states; also verify applicable non-text contrast.
 - [ ] **Dragging (SC 2.5.7, AA):** test every drag operation with a simple pointer alternative that does not require dragging; document the essentiality or user-agent exception, if any.
 - [ ] **Consistent help (SC 3.2.6, A):** compare pages in the same set and confirm repeated help mechanisms retain the same relative order, unless the user initiated a change.
 - [ ] **Redundant entry (SC 3.3.7, A):** run multi-step processes and confirm auto-population or selection of previously provided information, or record the applicable exception.
 - [ ] **Authentication (SC 3.3.8, AA):** test the whole flow, including MFA, without requiring unassisted memorization, solving, or transcription; confirm password-manager and paste support when they are the chosen mechanism.
 - [ ] **User flow and announcements:** manually test dynamic interactions without a mouse. Confirm DOM-present regions announce non-urgent messages through `role="status"` or `aria-live="polite"`, reserve `role="alert"` for urgent errors, and work in supported browser and assistive-technology combinations.
+- [ ] **Composite content:** informative multi-node visuals have one meaningful representation, decorative fragments are not announced, code remains readable as text, code controls have names, and copy/result status is announced through the intended region.
 - [ ] **Zoom and reflow:** text resizes up to 200% without loss of content or function (SC 1.4.4); content reflows at 320 CSS px width — equivalent to 400% zoom on a 1280px viewport — without two-dimensional scrolling (SC 1.4.10). Preserve flexibility using relative units (rem/em).
 - [ ] **Color and perception:** no functional loss when color is unavailable; confirm the additional channel appropriate to the meaning without requiring universal visual redundancy.
 - [ ] **Exceptions audit:** `EXCEPTIONS.md` reviewed — every active entry has a risk owner, approver, tracking issue, and expiry; no expired entries left unaddressed.

package/ENG/design-code-eng.md

@@ -3,7 +3,7 @@ name: design-code-eng
 language: en
 description: "Visual direction, UX, motion, and perceived performance for premium digital experiences."
 version: "2026.09"
-last-reviewed: "2026-08-17"
+last-reviewed: "2026-08-31"
 guide-id: design
 requires-gates:
   - design
@@ -261,6 +261,27 @@ Canvas, WebGL, SVG displacement, and Liquid Glass effects follow the **normative
 
 ## Premium Components (measurable defaults)
 
+### Component state contract
+
+Before polishing an interactive or data-bearing component, list the states it
+can actually reach. Use only the applicable states; this is a review aid, not a
+requirement to manufacture every variant.
+
+- **Resting and interaction:** default, hover where supported, focus-visible,
+  and active/pressed.
+- **Availability:** disabled and loading when the operation or dependency is
+  unavailable or in progress.
+- **Data and outcome:** empty, selected, expanded/collapsed, success, and error
+  when the component can display those conditions.
+
+Every reachable state must preserve the component's semantic name, action,
+focus behavior, contrast, and a non-color cue where color alone would be
+ambiguous. Define the authoritative transition for asynchronous states,
+including cancellation or a repeated request, so an interrupted operation
+cannot leave stale loading, success, or error feedback. Verify reachable
+transitions with interaction and semantic checks; a screenshot can show an
+appearance but cannot prove the state behavior or accessibility.
+
 **Primary button**
 
 - Padding: `14px 28px` (mobile `12px 24px`)

package/LOOP_ENGINEERING.md

@@ -24,6 +24,7 @@
 - [Proportional Planning](#proportional-planning)
 - [Execution Loop](#execution-loop)
 - [Verification & Regression](#verification-and-regression)
+- [Structural Quality Feedback](#structural-quality-feedback)
 - [Evidence-Driven Correction](#evidence-driven-correction)
 - [Precedence & Stop Conditions](#precedence)
 - [Final Delivery](#final-delivery)
@@ -1208,6 +1209,33 @@ Choose checks that match the artifact and risk.
 Regression depth grows with risk: specific check, related tests, then suite,
 build, and integration validation when reasonable.
 
+<a id="FL-SQ-001"></a> **FL-SQ-001 — Structural-quality evidence MUST remain provider-neutral, task-bound, delta-first, and separate from other verification dimensions.**
+
+### Structural quality feedback
+
+Structural quality is an optional provider-neutral verification dimension. It
+is a measurement of dependency structure, not a guide, a static analyzer built
+into ForgeLoop, or a universal software-quality score. The external provider
+remains a replaceable sensor while ForgeLoop owns policy and evidence.
+
+When enabled, capture a task-bound baseline after planning and immediately
+before execution. In `VERIFYING`, record the current-cycle evaluation before
+entering `REVIEWING`. A gate requires a comparable current-cycle pass; observe
+mode exposes the result or limitation without adding a completion blocker;
+off mode does not resolve or launch a provider.
+
+The baseline is immutable after `EXECUTING`. Provider identity/version, policy,
+route, contract, scope, and rules drift makes observations incomparable. A
+regression follows the existing `VERIFYING -> DIAGNOSING -> CORRECTING ->
+VERIFYING` loop with evidence-backed diagnosis; ForgeLoop does not fabricate a
+diagnosis. Do not claim `PASS` for unavailable or malformed evidence.
+
+Optional optimization is bounded, advisory, and scope-safe. It may use at most
+two extra evaluations in a verification cycle, never becomes required for
+completion, never widens claims, and never chases a perfect score. See
+[`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) for the provider
+contract, policy fields, commands, artifact layout, and Sentrux boundary.
+
 ### Executable Policy & Autonomy-Preserving Invariants
 
 ForgeLoop enforces executable verification rules (`.forgeloop/policy/rules.json`) that evaluate constraints on code and artifacts.
@@ -1348,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
@@ -1371,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;

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,
@@ -506,6 +537,7 @@ The ownership boundary for these extensions is explicit:
 | Handoff envelope | Creates immutable protocol-derived snapshots and verifies their digest and ledger relationships | Supplies any descriptive note or recipient hint; it cannot turn the envelope into delegation or evidence |
 | Responsibility contract | Validates allowed/read-only paths, required checks, and frozen-input fingerprints | Chooses the optional boundary and performs the work inside it |
 | Verification scope | Resolves `AUTO`, `CHANGED`, `CLAIMED`, or `FULL`, binds scoped-checker argv, and fails closed on stale or mismatched inputs | Declares checker configuration and consumes the returned scope without guessing a narrower one |
+| Structural quality | Owns provider-neutral baseline/evaluation artifacts, delta policy, typed check provenance, and lifecycle/completion semantics | Supplies or selects a runtime provider and consumes `quality-status`; it does not provide arbitrary executable or shell input |
 | RevisionProvider | Reads opaque revisions, exact bytes, normalized changes, and range coverage through the provider contract | Supplies or selects the provider and revision identifiers |
 | SigningProvider | Validates provider results and preserves `VERIFIED` versus `ATTESTED` semantics | Owns the external signer, identity/issuer policy, credentials, and availability |
 | Generic CI / MCP | Keeps canonical command, evidence, and trust semantics | Owns the platform job, transport, scheduling, and presentation layer |
@@ -526,6 +558,31 @@ OIDC tokens, and credentials outside ForgeLoop artifacts. Signing and
 verification may use an external provider, while the persisted statement stays
 deterministic and provider-neutral.
 
+<a id="FL-SQ-002"></a> **FL-SQ-002 — A structural-quality integration MUST preserve unavailable, malformed, stale, incomparable, and blocked provider results without promoting them to PASS.**
+
+## Structural quality integration
+
+Structural quality is an optional provider-neutral capability. The public
+integration API exposes `StructuralQualityProvider`, normalized detection and
+snapshot types, and runtime provider injection through the context. Project
+configuration selects only a registered provider name and policy; it cannot
+select an executable path, shell command, arbitrary argument vector, raw score,
+or baseline.
+
+The canonical commands are `quality-baseline` and `quality-verify` for bounded
+provider execution and task mutation, plus read-only `quality-status`. MCP and
+the integration API consume the same declarative command definitions and
+preserve `PASS`, `FAIL`, `BLOCKED`, and `NOT_OBSERVED` without duplicating
+lifecycle logic. The read-only `task/structural-quality` resource never starts
+the provider.
+
+The built-in `sentrux` provider uses the local MCP stdio boundary, requires a
+supported version, and keeps output, timeout, path, and secret handling inside
+ForgeLoop's normalized evidence boundary. Sentrux is not a runtime dependency;
+installation and analytics preferences remain user-managed. Quality evidence
+does not replace behavioral, security, performance, accessibility, review,
+publication, or production-readiness evidence.
+
 ## Executable Policy Protocol Integration
 
 ForgeLoop integrates executable verification rules directly into the lifecycle:

package/QUALITY_SCORECARD.md

@@ -15,6 +15,7 @@ policy are all present.
 | Portability | Node 20/22/24 Linux depth, OS smoke coverage, path/line-ending fixtures, and adapter compatibility evidence. |
 | Observability | `inspect`/`status`/`validate-protocol` shared derived state classification, real schema health, shared evidence, rich doctor findings, receipts, and no telemetry. |
 | Completion enforcement | Canonical contract, persisted route, guide-declared gates, preflight, phase ledger, structured checks, evidence coverage, `audit`, `report`, and `complete` validators. |
+| Structural quality feedback | Provider-neutral baseline and delta policy, five root-cause scores, typed task artifacts, bounded Sentrux MCP adapter, gate/observe semantics, and corrective lifecycle integration. |
 | Agent lifecycle navigation | Read-only `forgeloop next` decisions, stable action/reason output, persisted-state safety, and adapter guidance at lifecycle boundaries. |
 | Execution → Verification handoff | Legal `EXECUTING` → `VERIFYING` transition, implementation-step reconciliation, and preservation of verification evidence. |
 | Pre-contract autonomy — structural | Blocking vs Non-Blocking Decisions policy, classify-before-ask invariant, PRE-QUESTION CHECK, explicit ASSUMPTION / source=agent-default recording, contract-before-clarification ordering, deterministic reason-code helper, and positive/negative tests. |
@@ -101,6 +102,7 @@ are both present:
 | Security boundary | realpath containment, bounded JSON, `THREAT_MODEL.md`, secret-free artifacts, authority and no-runtime rules | `tests/security-limits.test.js`, Markdown/loop validators, and `scripts/scan_secrets.py` |
 | Cross-artifact conformance | `src/core/conformance.js`, `classifyLoadedWorkState`, and `forgeloop validate-protocol --contract-file` | `tests/conformance.test.js`, `tests/validate-protocol-cli.test.js`, and protocol fixtures covering precedence and stale evidence |
 | Protocol preparation and completion | `src/core/preflight.js`, `src/core/completion.js`, `src/core/events.js`, policy packs, and portable bundles | `tests/preflight.test.js`, `tests/completion.test.js`, `tests/lifecycle.test.js`, `tests/policy.test.js`, and `tests/bundle.test.js` |
+| Structural quality feedback | `docs/STRUCTURAL_QUALITY.md`, `LOOP_ENGINEERING.md`, `src/core/structural-quality/`, quality CLI commands, lifecycle projections, and `schemas/structural-quality.schema.json` | Structural-quality policy, provider, lifecycle, Sentrux adapter, artifact, bundle, and real-provider E2E tests; local Sentrux 0.5.7 cycle-regression scenario verified |
 | 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 |

package/README.md

@@ -31,11 +31,13 @@ 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)
 - **Artifact & schema reference** → [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
 - **Operational recipes** → [`docs/RECIPES.md`](./docs/RECIPES.md)
+- **Structural quality feedback** → [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md)
 - **Troubleshooting & error codes** → [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
 - **Code attestation & revision coverage** → [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **System architecture & safety** → [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) & [`THREAT_MODEL.md`](./THREAT_MODEL.md)
@@ -70,6 +72,7 @@ changed the repository.
 | Accessibility | [`ENG/accessibility-eng.md`](./ENG/accessibility-eng.md) |
 | Web games | [`ENG/games-code-design-web-eng.md`](./ENG/games-code-design-web-eng.md) |
 | Documentation quality | [`ENG/documentation-quality-eng.md`](./ENG/documentation-quality-eng.md) |
+| Structural quality feedback | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) |
 
 Each guide declares its name, language, version, and review date in
 frontmatter. Repository validators keep the catalog and metadata synchronized.
@@ -124,6 +127,23 @@ does not prove authorship or absolute security. See
 [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) for configuration,
 read-only verification, signatures, and revision-range coverage.
 
+### Optional structural quality feedback
+
+Projects may enable a provider-neutral structural-quality comparison. Capture
+an immutable baseline before execution, verify the current cycle, and let the
+configured `off`, `observe`, or `gate` mode determine whether the result is
+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
@@ -220,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:
 
@@ -292,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

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