@cassiomc1/forgeloop 1.1.0 → 1.2.1

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-10"
+last-reviewed: "2026-08-17"
 guide-id: design
 requires-gates:
   - design
@@ -342,7 +342,10 @@ Select references for a product problem; they do not override project tokens or
 
 - **Technical diagrams and architecture flows**: for polished Mermaid-based architecture and workflow diagrams, use [Beautiful Mermaid by Craft](https://agents.craft.do/mermaid) when relevant; preserve canonical Mermaid source, local versioned SVG assets, and do not treat presentation tooling as a mandatory protocol gate or runtime dependency.
 - **Component source and interaction inspiration**: use [21st.dev](https://21st.dev/) to study components and interactions; inspect each source, dependency, community contribution, and premium-material term before adoption.
-- **Component and motion inspiration**: use [React Bits](https://reactbits.dev/) to study component and motion behavior; distinguish public/free material from React Bits Pro and inspect each source/dependency license.
+- **AI-agent and conversational UI reference**: use [AIcss](https://www.aicss.dev/) to study specialized AI-agent and assistant interfaces (streaming responses, tool/action states, diffs, citations, structured outputs, agent inputs, and approval cards) when the target actually has an AI-agent surface.
+- **React component and motion reference**: use [React Bits](https://reactbits.dev/) to discover animated React components and interaction patterns, and inspect the [React Bits source repository](https://github.com/DavidHDev/react-bits) before adopting code. Use it only when the target stack is React or when a deliberate, reviewed adaptation is appropriate. Prefer the smallest component or pattern that solves the product need; do not install or copy the entire library by default. Inspect the exact component source, transitive dependencies, license/usage terms, accessibility behavior, reduced-motion behavior, responsive behavior, and runtime cost before adoption. Adapt tokens, typography, spacing, states, semantics, and motion to the target project's design system instead of preserving React Bits defaults.
+- **React and Next.js animated components**: use [beUI](https://beui.dev/) and its [source repository](https://github.com/starc007/ui-components) to study React/Next.js animated components built with Motion and Tailwind; prefer source-level adoption of the smallest matching component when the target stack fits.
+- **Page and theme transitions**: use [Transition Kit](https://transition-kit.space/) and its [source repository](https://github.com/AbdullahMukadam/Transition-kit) as a reference for CSS-first page and theme transitions built around the View Transitions API; use as progressive enhancement only with functional fallback.
 - **Component inspiration**: use [Fancy Components](https://www.fancycomponents.dev/) to study component composition; verify its terms separately from Motion, Tailwind, shadcn, or other dependencies.
 - **Motion primitives**: use [Motion Primitives](https://motion-primitives.com/) to study discrete interaction patterns; distinguish documented open-source material from its Pro offering and verify component/dependency terms.
 - **Component and design-system research**: use [Component Gallery](https://component.gallery/) for comparison, not for license assumptions.
@@ -351,6 +354,103 @@ Select references for a product problem; they do not override project tokens or
 - **Typography discovery**: verify each [UNCUT](https://uncut.wtf/) font's author, license, weights, and hosting rights.
 - **Creative coding and WebGL**: [cables.gl](https://cables.gl/) requires a semantic fallback, pause/offscreen behavior, a performance budget, and asset/operator provenance.
 
+### External UI/component reference adoption
+
+External galleries, component registries, motion libraries, and UI references are discovery inputs, not product requirements.
+
+Before materially adopting an external component or interaction:
+
+1. define the concrete UI need first;
+2. confirm the target stack and existing design system;
+3. inspect the exact component/source rather than relying on a gallery preview;
+4. verify current license/terms and any premium/free boundary;
+5. inspect runtime dependencies and avoid introducing a second animation or UI stack without a measured reason;
+6. verify keyboard/focus semantics, contrast, responsive behavior, touch, loading/error/disabled states, and reduced motion;
+7. evaluate bundle/runtime cost and browser/platform support;
+8. adapt the smallest useful source into the target project's tokens, architecture, and component conventions;
+9. record source/provenance when materially adopted;
+10. re-run target-project verification after adaptation.
+
+Do not install or copy an entire component library merely because one example looks useful. When React Bits, beUI, Motion Primitives, or another motion/component source could all satisfy the same need, choose one smallest compatible implementation; do not combine libraries for variety. ForgeLoop itself must not gain a dependency on any resource listed in this section.
+
+### React Bits — operational use for React interfaces
+
+React Bits is an optional implementation/reference source for high-finish React interfaces. It is not a required ForgeLoop tool, protocol dependency, verification dependency, or design-system replacement.
+
+Use it when:
+
+- the target application uses React;
+- a concrete interaction, text treatment, background, reveal, or UI component would materially improve the product experience;
+- implementing the behavior from scratch would add unnecessary design or engineering cost;
+- the effect fits the selected motion intensity and visual direction.
+
+Do not use it when:
+
+- the target is not React and adaptation would add more complexity than value;
+- the component exists only as decoration without a product or communication purpose;
+- the same result already exists in the target project's design system;
+- the component violates the project's accessibility, performance, security, dependency, or browser-support constraints;
+- a static or simpler CSS/HTML implementation communicates the same result more clearly.
+
+Adoption workflow:
+
+1. **Define the need first.** Identify the concrete UI or communication problem before browsing components.
+2. **Confirm the target stack.** Verify React version, styling strategy, TypeScript/JavaScript choice, SSR/CSR boundary, and existing animation/runtime libraries.
+3. **Inspect the source.** Review the exact component in the [React Bits repository](https://github.com/DavidHDev/react-bits), not only the visual demo.
+4. **Check usage terms.** Verify the current license and any component-specific dependency or attribution requirements before copying or installing code.
+5. **Choose the smallest variant.** Prefer one component/pattern and the variant matching the project (JS/TS and CSS/Tailwind); do not add unrelated components.
+6. **Prefer local adaptation.** Adapt the component into the target project's component structure and semantic tokens rather than importing a visual identity wholesale.
+7. **Preserve semantics.** Text, controls, navigation, forms, focus states, errors, status information, and primary actions must remain semantic and usable without decorative motion.
+8. **Respect reduced motion.** Provide a static or substantially reduced alternative under `prefers-reduced-motion`; essential information must never depend on animation.
+9. **Bound runtime cost.** Lazy-load expensive effects when practical, pause continuous animation outside the viewport or on hidden pages, and avoid adding duplicate animation/runtime libraries without justification.
+10. **Verify the result.** Test keyboard/focus behavior, contrast, 320 CSS px reflow, touch behavior, reduced motion, console/runtime errors, and the project's performance budget.
+11. **Record provenance.** When code or a material implementation pattern is adopted, record React Bits as an external source in the task/project attribution or source record when applicable.
+
+ForgeLoop runtime must not gain a dependency on React Bits as a result of this guidance. Any installation belongs to the target project and remains subject to normal authorization and dependency policy.
+
+### AIcss — contextual AI-agent and conversational UI reference
+
+[AIcss](https://www.aicss.dev/) is a specialized reference for AI-agent and conversational product surfaces (streaming responses, tool/action execution states, diffs, citations, structured outputs, agent inputs, and approval/status cards).
+
+Use AIcss as a candidate only when at least one of these is in scope:
+
+- streamed assistant output;
+- visible tool execution/status;
+- source citations;
+- file/code diffs;
+- structured agent results;
+- agent-specific input/approval interaction.
+
+For ordinary SaaS, editorial, portfolio, or marketing UI without those surfaces, use general component/design references instead.
+
+> [!IMPORTANT]
+> **Safety and Hidden-Reasoning Boundary**: AIcss labels such as "thinking" or "reasoning" describe presentation patterns, not an evidence source. They do not authorize exposing private chain-of-thought or hidden model state. Prefer concise observable progress/status information that the target product is permitted to show.
+
+### beUI — React/Next animated component source
+
+[beUI](https://beui.dev/) and its source repository [starc007/ui-components](https://github.com/starc007/ui-components) provide copy-paste animated components for React/Next.js using Motion and Tailwind.
+
+- **Smallest-Adoption Rule**: Prefer source-level adoption of the smallest matching component. Do not run its shadcn command, install its agent skill, or add Motion/Tailwind merely because the catalog is available. Any installation belongs to the target project and follows normal authorization and dependency policy.
+- **Verification Expectations**: For any materially adopted animated component, verify keyboard/focus access, touch targets, reduced-motion behavior (`prefers-reduced-motion`), responsive reflow at 320 CSS px, loading/error/disabled states, console/runtime errors, and bundle/runtime impact.
+
+### Transition Kit — progressive-enhancement page and theme transitions
+
+[Transition Kit](https://transition-kit.space/) and its source repository [AbdullahMukadam/Transition-kit](https://github.com/AbdullahMukadam/Transition-kit) provide CSS-first page and theme transitions built around the View Transitions API.
+
+For Transition Kit or any View Transitions API effect:
+
+1. **Functional Base First**: The page navigation or theme switch action must work completely without the transition; enhancement never owns essential meaning or action.
+2. **Implementation-Time Capability Check**: Check current target-browser support for the View Transitions API at implementation time rather than assuming static support tables.
+3. **Graceful Fallback**: Unsupported browsers must receive a functional, immediate fallback without errors or layout shifts.
+4. **Reduced Motion**: Under `prefers-reduced-motion`, provide an equivalent static or near-instant path.
+5. **State Preservation**: Ensure focus management, navigation/history, scroll restoration, theme persistence, and interactive controls remain correct during and after transitions.
+6. **Motion Budget**: Transition duration and easing must respect the product motion budget.
+7. **No Protocol Dependency**: Adapt copied CSS/JS into the target project architecture instead of creating a ForgeLoop dependency.
+
+### Target-Project React Diagnostics Cross-Reference
+
+For React-specific supplemental diagnostics after implementation, including design-tagged findings when supported by the adopted version, see [`test-code-eng.md`](./test-code-eng.md). React Doctor is a verifier candidate, not a component/design source.
+
 ---
 
 ## UX, Accessibility, and Quality

package/ENG/taste-frontend-eng.md

@@ -3,7 +3,7 @@ name: taste-frontend-eng
 language: en
 description: "Contextual visual-taste review for premium frontend and brand-heavy work."
 version: "2026.09"
-last-reviewed: "2026-08-10"
+last-reviewed: "2026-08-17"
 guide-id: taste
 ---
 
@@ -107,8 +107,12 @@ Use the existing product system when one is present. If the target has no
 system, choose a small coherent set of semantic tokens, components, states,
 and usage rules that the team can maintain. A vendor guide, gallery, template,
 or AI output can inform a direction, but it is not evidence of product fit,
-license, accessibility, or performance. Keep any external reference in the
-task's source and attribution records; do not add a network dependency to
+license, accessibility, or performance. For external component, AI-interface,
+or motion references — including React Bits, AIcss, beUI, and Transition Kit
+when contextually applicable — follow the canonical adoption rules in
+[`design-code-eng.md`](./design-code-eng.md) rather than treating a gallery
+component as a project design-system default. Keep any external reference in
+the task's source and attribution records; do not add a network dependency to
 ForgeLoop runtime.
 
 ## Visual Pre-Flight

package/ENG/test-code-eng.md

@@ -68,6 +68,7 @@ A tool is a candidate, not a ranking winner. Record the decision in the reposito
 | Real services | [Testcontainers](https://testcontainers.com/), stack-native harness | required fidelity, container availability, time, and CI isolation |
 | HTTP/event contracts | [Pact](https://docs.pact.io/), OpenAPI/JSON Schema/GraphQL schema | consumer/provider ownership, versioning, and compatibility across deployments |
 | Performance | [k6](https://grafana.com/docs/k6/latest/), [Gatling](https://docs.gatling.io/), [JMeter](https://jmeter.apache.org/usermanual/), or [Locust](https://docs.locust.io/) | protocol, load model, volume, distribution, metrics, and team operability |
+| React code quality diagnostics | [React Doctor](https://github.com/millionco/react-doctor) plus the project's existing lint/test/type/a11y/security tools | candidate supplemental scan for React targets; evaluate framework compatibility, version pinning, network/install policy, telemetry policy, false positives, changed-code scope, and whether findings overlap existing gates |
 
 Mocks, stubs, and fakes belong in isolated tests. For integration, prefer disposable dependencies equivalent to production when this reduces relevant differences. Typing, linting, and static analysis complement tests; they do not replace executing behavior.
 
@@ -84,10 +85,54 @@ Run only the rows applicable to the product and recorded risk. A tool name witho
 | Laravel | middleware, validation, policies/auth, queues, and database are not exercised by a pure unit test | separate unit from feature/HTTP/database tests; fake only the boundary outside the oracle and verify persisted effects; approve a critical endpoint with applicable auth, validation, response, database, and job/event evidence | [Laravel — testing](https://laravel.com/docs/12.x/testing), [HTTP tests](https://laravel.com/docs/12.x/http-tests), and [database testing](https://laravel.com/docs/12.x/database-testing) |
 | HTML and HyperFrames | invalid markup, overflow, nondeterministic timing, or an incorrect critical frame | validate HTML; run `hyperframes lint`/`hyperframes check` when exposed by the pinned version; preview/render declared formats and review critical frames/boundaries; any structural, timing, or layout error blocks | [WHATWG — validators](https://whatwg.org/validator/), [Nu HTML Checker](https://validator.w3.org/nu/), and [HyperFrames](https://hyperframes.heygen.com) |
 | CSS and visual regression | cascade, responsiveness, theme, font, or environment changes layout/behavior | run Stylelint and semantic/interaction assertions; compare screenshots only in a controlled environment and risk matrix; diffs require explicit review and the gate does not depend on a generated CSS snapshot | [Stylelint](https://stylelint.io/user-guide/get-started/) and [Playwright visual comparisons](https://playwright.dev/docs/test-snapshots) |
+| React quality diagnostics | regressions in state/effects, performance, accessibility, security, or component architecture | run React Doctor when pinned/authorized; scope to changed files; triage findings against project risk and preserve exit code and findings as check evidence | [React Doctor](https://github.com/millionco/react-doctor) |
 | Terraform | valid configuration produces unexpected replace/destroy, cost, exposure, or state | run `fmt`/`validate`, test module assertions, and review `plan`; use a dedicated account/environment for `terraform test` that creates resources; block unexpected actions and confirm cleanup of every test resource | [Terraform validate](https://developer.hashicorp.com/terraform/cli/commands/validate), [test](https://developer.hashicorp.com/terraform/cli/commands/test), and [plan](https://developer.hashicorp.com/terraform/cli/commands/plan) |
 | Kubernetes and containers | a schema accepted locally fails in-cluster, or rollout/probe/rollback/image behavior diverges | use strict validation and server-side dry-run; use an ephemeral cluster when rollout/controller risk justifies it; run build checks and image smoke; the gate covers probes, resources, permissions, applicable rollback, and cleanup | [kubectl apply](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_apply/) and [Docker build checks](https://docs.docker.com/reference/build-checks/) |
 | Ansible | a playbook is not idempotent, makes a destructive change, or reaches an incorrect state | run syntax/check when safe and a Molecule scenario with converge, verify, idempotence, and destroy according to risk; approve only if the second convergence causes no unintended change and the environment is cleaned | [Ansible Molecule](https://docs.ansible.com/projects/molecule/) and [test sequence](https://docs.ansible.com/projects/molecule/usage/) |
 
+### React Doctor — optional supplemental React diagnostics
+
+For a React target, [React Doctor](https://github.com/millionco/react-doctor) may be used as a supplemental static/quality scan when it is already available or its execution/install is explicitly authorized. It reports diagnostics across React correctness/state, performance, architecture, security, accessibility, and related design rules.
+
+It does not replace the target's type checker, linter, unit/integration/E2E tests, security review, accessibility review, or performance evidence.
+
+Before using it:
+
+1. **Identify version**: Determine the exact pinned/adopted version.
+2. **Follow authority policy**: Determine whether invocation downloads code or changes the environment; follow the target's authorization/network policy.
+3. **Telemetry policy**: Review the tool's current telemetry behavior and disable telemetry when target policy requires it.
+4. **Scope appropriately**: Select a scope that matches the task (`changed`/equivalent when supported) rather than turning an unrelated existing backlog into a new completion requirement.
+5. **Preserve evidence**: Retain the actual findings, exit status, version, and command as evidence.
+6. **Risk-based triage**: Triage findings by real project risk instead of treating the numeric score as the pass/fail oracle.
+
+Command examples:
+
+```bash
+# If the project already has a pinned React Doctor command:
+npm run react-doctor -- --verbose --scope changed
+
+# If an authorized one-off remote invocation is explicitly allowed:
+npx react-doctor@<PINNED_VERSION> --no-telemetry --verbose --scope changed
+```
+
+> [!NOTE]
+> Verify current upstream CLI syntax before execution; external command flags are not part of the ForgeLoop protocol contract.
+
+Evidence integration:
+
+A successful observed run may be recorded through ForgeLoop's existing check mechanism:
+
+```bash
+forgeloop run-check \
+  --task <task-id> \
+  --id react-doctor-changed \
+  --requirement react-quality \
+  -- <project-owned-react-doctor-command>
+```
+
+- **Score Semantics**: A React Doctor score is diagnostic telemetry, not a universal gate. The target contract or project policy may define a versioned threshold, but absent such a contract ForgeLoop evaluates concrete findings against applicable correctness, accessibility, security, performance, and architecture requirements.
+- **False Positives**: When a finding is disputed, inspect the exact rule and project context. A suppression/config change is a code-quality policy change and requires the same review as other lint/static-analysis configuration changes; do not disable a rule merely to make a score increase.
+
 ## Fixtures, cassettes, and oracles
 
 - Prefer minimal synthetic data. When fixtures are derived from production, anonymize them irreversibly and review reidentification, retention, and licensing risk before committing.

package/LOOP_ENGINEERING.md

@@ -592,6 +592,57 @@ the current cycle. Lifecycle-owned terminal criteria such as validator-backed
 `record-check` claims. Compound `ALL` checks cannot pass while any declared
 component is failed, blocked, partial, or not verified.
 
+### Diagnosis Ledger and Evidence-Driven Correction
+
+When a check fails during verification (`VERIFYING → DIAGNOSING`), the actor must record an append-only diagnosis event in the lifecycle ledger before entering `CORRECTING`:
+
+```bash
+forgeloop record-diagnosis \
+  --hypothesis="Specific root-cause hypothesis explaining the verification failure" \
+  --failure-class="VERIFICATION_FAILURE" \
+  --evidence-ref="check-id" \
+  --settled-by="Observable condition that settles or falsifies the hypothesis" \
+  --next-safe-action="Smallest safe local action to address the hypothesis"
+```
+
+- **Single Source of Truth**: The append-only, hash-chained `events.ndjson` is the sole authority for diagnosis chronology (`DIAGNOSIS_RECORDED` events). The mutable `work-state.diagnosedHypothesis` field is maintained strictly as a backward-compatibility projection.
+- **Evidence Binding**: `evidence-ref` must reference at least one failed or blocked check from the active `verificationCycle`.
+- **Information Gain Classification**: Each diagnosis is classified by comparing its normalized semantic fingerprint (`sha256(failureClass:normalizedHypothesis:sortedEvidenceRefs)`) against previous task diagnoses:
+  - `FIRST_DIAGNOSIS`: Initial diagnosis for the task.
+  - `NEW_HYPOTHESIS`: Distinct hypothesis with previously observed evidence.
+  - `NEW_EVIDENCE`: Same hypothesis supported by newly observed evidence checks.
+  - `NEW_HYPOTHESIS_AND_EVIDENCE`: Both hypothesis and evidence references are new.
+  - `NONE`: Repeating the previous hypothesis with the exact same evidence.
+- **Idempotent Recovery in the Same Cycle**: Retrying `record-diagnosis` with the identical hypothesis and evidence within the *same* verification cycle is idempotent. It reuses the existing event, repairs or synchronizes `work-state.diagnosedHypothesis`, advances `work-state.lastUpdated`, and returns `idempotent: true` without appending a duplicate event or triggering a false stall.
+- **No Retry Without Information Gain**: Repeating the same hypothesis and evidence in a *subsequent* verification cycle produces `informationGain: NONE`. Such diagnoses are recorded in the event ledger for auditability but cannot authorize a correction phase transition (`DIAGNOSING → CORRECTING` fails with `E_DIAGNOSIS_NO_NEW_INFORMATION`, and `forgeloop next` returns `CHANGE_STRATEGY`). Superficial alterations to `settled-by`, `next-safe-action`, or formatting without changing the underlying hypothesis or evidence references do not generate information gain.
+- **Legacy Compatibility Invariant**: Tasks created under older protocol-v1 revisions that have `diagnosedHypothesis` populated in `work-state.json` without a corresponding `DIAGNOSIS_RECORDED` event remain readable. However, `forgeloop next` returns `RECORD_DIAGNOSIS` and `DIAGNOSING → CORRECTING` fails with `E_DIAGNOSIS_REQUIRED` until a formal diagnosis is appended via `forgeloop record-diagnosis`. ForgeLoop never synthesizes historical events automatically.
+
+### Progress Stall Detection (`forgeloop progress`)
+
+Task progress across iterative verification cycles is evaluated deterministically without heuristics, model confidence scores, or chain-of-thought introspection:
+
+- **Statuses**:
+  - `ADVANCING`: Failure counts are low, or new diagnostic information gain is present.
+  - `WATCH`: A single requirement has failed across 3+ distinct cycles with changing diagnoses, or the task has reached a high cycle count ($\ge 4$). High cycle count alone produces `WATCH`, never a hard stall.
+  - `STALLED`: The latest diagnosis has `informationGain: NONE` (global stall with signal `NO_DIAGNOSTIC_INFORMATION_GAIN`), or a specific requirement failed 3+ times with identical diagnoses (`REPEATED_FAILURE_WITH_SAME_DIAGNOSIS`).
+- **Requirement-Specific Attribution**: Stall signals are mapped to individual contract requirements strictly through `evidenceRefs → check → requirement`. A stall on one requirement does not fabricate false repeat-diagnosis signals for unrelated requirements.
+- **Strategy Change**: When stalled, `forgeloop next` returns action `CHANGE_STRATEGY` with error code `E_PROGRESS_STALLED`. This directs the actor to formulate a genuinely new root-cause hypothesis, gather independent diagnostic evidence, or change the technical approach.
+
+### Decision Settlement Criteria
+
+Unresolved contract decisions in `current-contract.unresolvedDecisions[]` can be paired with append-only settlement criteria bound to the active contract fingerprint:
+
+```bash
+forgeloop record-decision-criterion \
+  --decision="Exact text of unresolved decision" \
+  --settled-by="Criteria or guidance that settles the decision"
+```
+
+- **Contract Schema Compatibility**: `current-contract.unresolvedDecisions[]` remains an array of strings (`string[]`) under `protocolVersion: 1`. Criteria are persisted as `DECISION_CRITERION_RECORDED` events in `events.ndjson` bound to `contractFingerprint`.
+- **Guidance Surfacing**: `forgeloop next` surfaces recorded criteria in its blocker reasons as `SETTLEMENT_CRITERION` (for a single decision) or `SETTLEMENT_CRITERIA` with an `items[]` array (for multiple decisions). Decisions without recorded criteria do not receive fabricated guidance.
+- **Fingerprint Binding and Staleness**: A criterion is valid only while the contract fingerprint matches. If the contract is modified, previous criteria bound to older fingerprints are automatically ignored as stale.
+- **Non-Bypassing**: Recording a settlement criterion attaches advisory guidance only; it does not automatically resolve the decision or make preflight `READY`. The contract must still be explicitly updated or resolved before execution begins.
+
 ## Independent completion dimensions
 
 Local task completion, verification, publication, and production readiness are

package/ORCHESTRATOR_INTEGRATION.md

@@ -60,12 +60,14 @@ invariants and record why a skipped phase was not applicable.
 
 - `COMPLETE` requires verification evidence current to the task.
 - `BLOCKED` requires blocker evidence, a category, and a safe next action.
-- `CORRECTING` requires a diagnosed hypothesis and a changed evidence basis.
+- `CORRECTING` requires a diagnosed hypothesis recorded in the event ledger (`DIAGNOSIS_RECORDED`) with non-zero information gain (`informationGain !== "NONE"`).
 - `REVIEWING` cannot claim independent review when reviewer and implementer
   identities are equal.
 - `REVIEWING → VERIFYING` requires a persisted evidence-only completion
   rejection and starts a new `verificationCycle`.
-- A retry requires new evidence or a changed hypothesis.
+- A retry requires new evidence or a changed hypothesis; repeating the same diagnosis produces `informationGain: NONE` and stalls progression (`CHANGE_STRATEGY`).
+- `forgeloop progress` deterministically evaluates task progress across cycles as `ADVANCING`, `WATCH`, or `STALLED`.
+- `forgeloop record-decision-criterion` attaches contract-bound guidance to unresolved decisions without breaking the schema.
 
 ## Serializable interfaces
 

package/README.md

@@ -1,5 +1,9 @@
 # ForgeLoop — Verifiable Engineering Protocol
 
+<p align="center">
+  <img src="./docs/assets/forgeloop-readme-banner.svg" alt="ForgeLoop — Verifiable Engineering Protocol" width="100%">
+</p>
+
 [![Docs quality](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml)
 
 ForgeLoop is a portable, vendor-neutral protocol for AI-assisted development
@@ -108,10 +112,12 @@ forgeloop complete --task example-task --json
 `advance` changes protocol phase only; it never runs target commands.
 `run-check` classifies the exact argv before launch and records ForgeLoop-owned
 execution provenance. `record-check` stores an observation and never executes
-the text supplied to `--command`. `complete` validates the contract, route,
-gates, ledger, evidence, coverage, receipt, and freshness. `audit` is
-read-only. `report` exposes independent completion, publication, and
-production-readiness dimensions.
+the text supplied to `--command`. `record-diagnosis` appends an authoritative
+root-cause hypothesis to the event ledger. `progress` evaluates task
+progression and detects stalls deterministically. `complete` validates the
+contract, route, gates, ledger, evidence, coverage, receipt, and freshness.
+`audit` is read-only. `report` exposes independent completion, publication,
+and production-readiness dimensions.
 
 The status precedence is `INVALID` > `INCONSISTENT` > `STALE` > `INCOMPLETE` >
 `VALID`. A `READY` preflight is a resumable checkpoint: if its work state is

package/THIRD_PARTY_NOTICES.md

@@ -56,6 +56,16 @@ dependencies, version, and distribution conditions before adoption.
   workflow boundaries and public discoverability only.
 - Boundary: this repository links to Superpowers as a reference; it is not a dependency of `ForgeLoop`, and `ForgeLoop` does not copy, bundle, install, or vendor any Superpowers source, skill, hook, plugin, runtime, dependency, credential, or provider.
 
+### React Doctor
+
+- Project: [millionco/react-doctor](https://github.com/millionco/react-doctor).
+- Use in this collection: optional target-project React diagnostic/verifier
+  reference.
+- Boundary: React Doctor is not a ForgeLoop runtime dependency or universal
+  completion gate. ForgeLoop does not automatically download, install, execute,
+  configure, or enable its CI/agent integrations. Verify current upstream
+  license, CLI, telemetry, network behavior, and dependencies before use.
+
 ### Runtime and validator boundary
 
 The distributed CLI and repository validators use Node.js and Python standard
@@ -87,14 +97,27 @@ network behavior, and distribution terms separately.
 
 ## Design reference sites
 
-The following nine sites are references in the design guide. None is a
+The following sites are references in the design guide. None is a
 dependency of this collection or a blanket permission to reuse code, assets,
 fonts, templates, or other material.
 
 - [21st.dev](https://21st.dev/): component and template registry; check the
   terms for the specific author, community contribution, or paid material.
+- [AIcss](https://www.aicss.dev/): AI-agent interface pattern and component
+  reference; verify current terms, provenance, dependencies, and reuse rights
+  for the exact block before copying or redistributing it.
 - [React Bits](https://reactbits.dev/): component and motion reference; keep
   public/free material, React Bits Pro, and dependency terms separate.
+- [beUI](https://beui.dev/) / source
+  [starc007/ui-components](https://github.com/starc007/ui-components):
+  React/Next.js animated component reference; verify current terms, license,
+  Motion/Tailwind dependencies, and accessibility/reduced-motion behavior before
+  adoption.
+- [Transition Kit](https://transition-kit.space/) / source
+  [AbdullahMukadam/Transition-kit](https://github.com/AbdullahMukadam/Transition-kit):
+  CSS-first page/theme transition reference around the View Transitions API;
+  verify current terms, browser compatibility, and fallback behavior before
+  adoption.
 - [Fancy Components](https://www.fancycomponents.dev/): component reference;
   verify the linked source license and each dependency before reuse.
 - [Motion Primitives](https://motion-primitives.com/): motion reference; keep

package/docs/ARTIFACT_REFERENCE.md

@@ -160,7 +160,7 @@ Discovered repository facts, platforms, runtimes, and dependencies.
 
 <!-- forgeloop-doc: schema=event artifact=.forgeloop/task-state/<task-key>/events.ndjson -->
 
-The append-only cryptographic event ledger. Each line is a single JSON event object.
+The append-only cryptographic event ledger. Each line is a single JSON event object. Records authoritative chronological events including lifecycle milestones (`TASK_RECEIVED`, `CONTRACT_VALIDATED`, `ROUTE_VALIDATED`, `PREFLIGHT_READY`, `EXECUTION_STARTED`, `VERIFICATION_STARTED`), evidence-backed diagnoses (`DIAGNOSIS_RECORDED`), and decision settlement criteria (`DECISION_CRITERION_RECORDED`).
 
 #### Canonical Line Fields
 
@@ -254,7 +254,7 @@ Pre-implementation gate approval artifact recording decisions, bound artifact ha
 
 <!-- forgeloop-doc: schema=work-state artifact=.forgeloop/task-state/<task-key>/work-state.json -->
 
-The canonical, authoritative lifecycle work state.
+The canonical, authoritative lifecycle work state. Represents current checkpoint and resume state (`phase`, `checks`, `verificationCycle`, `lastUpdated`). Note: `diagnosedHypothesis` is maintained as a backward-compatibility projection of the latest diagnosis from `events.ndjson`.
 
 #### Canonical Fields
 

package/docs/CLI_REFERENCE.md

@@ -40,8 +40,8 @@ ForgeLoop uses a definition-driven command-line parser:
 | Category | Commands |
 | --- | --- |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`task-unlock`](#task-unlock) |
-| **Inspection & Diagnostics** | [`doctor`](#doctor), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`complete`](#complete), [`clear-state`](#clear-state), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-scope`](#task-scope) |
+| **Inspection & Diagnostics** | [`doctor`](#doctor), [`progress`](#progress), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
 | **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) |
 | **Policy & Auditing** | [`policy`](#policy), [`bundle`](#bundle) |
@@ -201,6 +201,33 @@ Creates a protocol/session activation marker for the current harness session.
   forgeloop activate --json
   ```
 
+### `record-decision-criterion`
+
+Records an append-only decision settlement criterion bound to the active contract fingerprint.
+
+- **Purpose**: Records settlement guidance or criteria for open contract decisions without modifying contract schema.
+- **When to use**: To attach settlement guidance to unresolved decisions in `current-contract.unresolvedDecisions[]`.
+- **Mutation**: Appends `DECISION_CRITERION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-decision-criterion: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)
+- `--decision <text>`: unresolved decision text matching current contract
+- `--settled-by <text>`: criteria or guidance that settles the decision
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-decision-criterion:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-decision-criterion \
+    --decision="Which authentication provider should be used?" \
+    --settled-by="Use provider supporting current session token middleware"
+  ```
+
 ### `advance`
 
 Advances the protocol lifecycle phase.
@@ -427,6 +454,39 @@ Records an observed or manual verification check result without executing comman
     --result "Verified contrast ratios exceed 4.5:1 across all color schemes"
   ```
 
+### `record-diagnosis`
+
+Records an append-only diagnosis event in the lifecycle event ledger for the active cycle.
+
+- **Purpose**: Records root-cause hypotheses, failure classes, and settlement criteria for failed verification checks.
+- **When to use**: In `DIAGNOSING` phase before advancing to `CORRECTING`.
+- **Mutation**: Appends `DIAGNOSIS_RECORDED` to event ledger and updates work state projection.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-diagnosis: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)
+- `--hypothesis <text>`: specific root-cause hypothesis explaining the verification failure
+- `--failure-class <class>`: canonical failure class taxonomy
+- `--evidence-ref <check-id>`: reference to failed/blocked check from current cycle (repeatable)
+- `--settled-by <text>`: falsification or settlement criteria for the hypothesis
+- `--next-safe-action <text>`: smallest safe action to address the hypothesis
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-diagnosis:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-diagnosis \
+    --hypothesis="Off-by-one index calculation in slice function" \
+    --failure-class="VERIFICATION_FAILURE" \
+    --evidence-ref="unit-tests" \
+    --settled-by="Test returns expected slice length" \
+    --next-safe-action="Adjust offset +1 in slice.js"
+  ```
+
 ### `validate-state`
 
 Validates `.forgeloop/work-state.json` structure, hash chain, and repository binding.
@@ -500,6 +560,29 @@ Performs comprehensive protocol validation across all active artifacts.
   forgeloop validate-protocol --json
   ```
 
+### `progress`
+
+Evaluates task progress across verification cycles and detects stalls deterministically.
+
+- **Purpose**: Evaluates whether iterative correction cycles are advancing, on watch, or stalled.
+- **When to use**: Any time during execution, verification, or diagnosis to inspect progress signals and prevent repeated ineffective retries.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:progress: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 progress evaluation as JSON
+
+<!-- END FORGELOOP GENERATED: cli:progress:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop progress --json
+  ```
+
 ---
 
 ## 5. Completion & Reporting

package/docs/GETTING_STARTED.md

@@ -237,10 +237,36 @@ forgeloop run-check --task task-contact-form-001 --id lint --requirement "npm ru
 
 If a check fails:
 
-1. Do not repeat the failed check blindly.
-2. Formulate a diagnostic hypothesis.
-3. Apply the correction.
-4. Re-run `forgeloop run-check`.
+1. Advance to `DIAGNOSING`:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to DIAGNOSING
+   ```
+
+2. Record an append-only root-cause diagnosis in the event ledger:
+
+   ```bash
+   forgeloop record-diagnosis \
+     --task task-contact-form-001 \
+     --hypothesis="Form validation regex incorrectly rejects valid domain formats" \
+     --failure-class="VERIFICATION_FAILURE" \
+     --evidence-ref="unit-tests" \
+     --settled-by="All domain validation unit tests pass" \
+     --next-safe-action="Update email domain regex in ContactForm.jsx"
+   ```
+
+3. Advance to `CORRECTING` and apply the fix:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to CORRECTING
+   ```
+
+4. Re-enter `VERIFYING` (advances `verificationCycle` monotonically) and re-run checks:
+
+   ```bash
+   forgeloop advance --task task-contact-form-001 --to VERIFYING
+   forgeloop run-check --task task-contact-form-001 --id unit-tests --requirement "npm test passes for contact form" -- npm test
+   ```
 
 ---
 

package/docs/RECIPES.md

@@ -18,6 +18,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 10. [Final Verification Before Pull Request](#recipe-10--final-verification-before-pull-request)
 11. [Run Multi-Task Workflows Concurrently](#recipe-11--run-multi-task-workflows-concurrently)
 12. [Migrate Legacy 1.0 Single-Task Layout](#recipe-12--migrate-legacy-10-single-task-layout)
+13. [Record Decision Settlement Criteria](#recipe-13--record-decision-settlement-criteria)
 
 ---
 
@@ -98,16 +99,29 @@ export FORGELOOP_TASK="task-001"
 forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
 # Output: status = failed
 
-# 2. Query next action (directs to DIAGNOSE)
-forgeloop next --json
+# 2. Advance to DIAGNOSING
+forgeloop advance --to DIAGNOSING
+
+# 3. Record append-only root-cause diagnosis in ledger
+forgeloop record-diagnosis \
+  --hypothesis="Edge case comparison operator <= instead of < in validator" \
+  --failure-class="VERIFICATION_FAILURE" \
+  --evidence-ref="unit-tests" \
+  --settled-by="Boundary test passes with status 400" \
+  --next-safe-action="Replace <= with < in validator.js"
 
-# 3. Formulate diagnosis and apply code fix in checkout
+# 4. Advance to CORRECTING and apply the fix
+forgeloop advance --to CORRECTING
+
+# 5. Re-enter VERIFYING (advances verificationCycle monotonically)
+forgeloop advance --to VERIFYING
 
-# 4. Re-run verification check
+# 6. Re-run verification check
 forgeloop run-check --id unit-tests --requirement "All tests pass" -- npm test
 
-# 5. Check audit
-forgeloop audit --json
+# 7. Advance to REVIEWING and complete
+forgeloop advance --to REVIEWING
+forgeloop complete --json
 ```
 
 ---
@@ -248,3 +262,18 @@ forgeloop task-migrate --json
 forgeloop task-list --json
 forgeloop status --json
 ```
+
+---
+
+### Recipe 13 — Record Decision Settlement Criteria
+
+```bash
+# 1. Record an append-only settlement criterion bound to the active contract
+forgeloop record-decision-criterion \
+  --task task-001 \
+  --decision="Which authentication provider should be used?" \
+  --settled-by="Use provider with native support for current JWT session tokens"
+
+# 2. Inspect next action (surfaces the guidance)
+forgeloop next --task task-001
+```