@cassiomc1/forgeloop 1.8.1 → 1.9.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)*
@@ -1075,3 +1099,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,8 +61,8 @@ 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) |
@@ -1235,6 +1235,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/KNOWLEDGE_SOURCES.md

@@ -0,0 +1,161 @@
+# 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.
+
+## 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.

package/docs/MCP.md

@@ -119,7 +119,7 @@ forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
 
 | Component | Current contract |
 | --- | --- |
-| ForgeLoop core package | `>=1.5.0 <2` dependency range; current repository generation `1.8.x` |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current repository generation `1.9.x` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |

package/docs/RECIPES.md

@@ -28,6 +28,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 20. [Configure Trusted Narrow Verification](#recipe-20--configure-trusted-narrow-verification)
 21. [Generate and Verify Code Attestation](#recipe-21--generate-and-verify-code-attestation)
 22. [Verify a Revision Range](#recipe-22--verify-a-revision-range)
+23. [Run Structural Quality Feedback](#recipe-23--run-structural-quality-feedback)
 
 ---
 
@@ -551,6 +552,36 @@ coverage gap or conflicting task digest is invalid; provider or invocation
 failure is an error. This post-completion range result is distinct from the
 pre-completion verification scope used by one checker.
 
+---
+
+### Recipe 23 — Run Structural Quality Feedback
+
+Enable `structuralQuality` in `.forgeloop/config.json` with `observe` for
+non-blocking evidence or `gate` for a completion requirement. The configured
+provider is selected by name; executable paths and shell fragments are not
+accepted.
+
+```bash
+# Capture after planning and before execution.
+forgeloop quality-baseline --task task-001 --json
+
+# Enter the normal lifecycle and evaluate the current verification cycle.
+forgeloop advance --task task-001 --to EXECUTING --json
+forgeloop advance --task task-001 --to VERIFYING --json
+forgeloop quality-verify --task task-001 --json
+
+# Inspect evidence without starting the provider.
+forgeloop quality-status --task task-001 --json
+```
+
+In `gate` mode, a failed comparison follows the existing
+`VERIFYING -> DIAGNOSING -> CORRECTING -> VERIFYING` loop. Record a diagnosis
+from the evaluation artifact before correcting code. In `observe` mode,
+unavailable or incomparable evidence remains visible as `NOT_OBSERVED` and
+does not block completion by itself. See
+[`STRUCTURAL_QUALITY.md`](./STRUCTURAL_QUALITY.md) for policy, provider,
+Sentrux, bundle, and error-code details.
+
 ## Run ForgeLoop through MCP (safe mode)
 
 Start the local MCP adapter and inspect what it exposes: