@cassiomc1/forgeloop 1.1.1 → 1.2.2

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

@@ -17,7 +17,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 5. Make the minimum change, run specific checks, and run proportional regression checks.
 6. Diagnose failures before fixing them; do not repeat attempts without new evidence.
 7. Request authority for unrelated actions, installations, and publications. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-8. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+8. Before creating or activating new lifecycle state: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.
 9. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 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.

package/.github/copilot-instructions.md

@@ -14,7 +14,7 @@ Use these instructions across the repository while preserving local rules.
 - Make the smallest coherent change; validate with specific and regression checks.
 - Diagnose causes before fixing failures; do not make unverified attempts.
 - Do not install software, publish, delete, or alter external state without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-- Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+- Before creating or activating new lifecycle state: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.
 - After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
 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.

package/AGENTS.md

@@ -12,7 +12,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. Make the smallest coherent change, run specific checks, and proportional regression checks.
 1. Diagnose failures before fixing; do not repeat attempts without new evidence.
 1. Do not install software, publish, delete, or migrate data without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+1. Before creating or activating new lifecycle state: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.
 1. Before implementation, create/validate the task contract (`contract.json`), persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
 1. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.

package/CLAUDE.md

@@ -14,7 +14,7 @@ When working in this repository:
 1. Make small changes, run specific checks, and run proportional regression checks.
 1. Investigate root causes before fixing failures; do not make unverified attempts.
 1. Request authority for unrelated installations, publications, deletions, or migrations. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
-1. Before creating or activating new lifecycle state: if `.forgeloop/work-state.json` exists, inspect the existing task, reconcile continuity when present, inspect the checkout, and run `forgeloop next`. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task.
+1. Before creating or activating new lifecycle state: discover existing tasks first with `forgeloop task-list --json`; if an existing task is selected or identifiable, use `forgeloop next --task <id> --json` before creating another task, reconcile continuity when present, and inspect the checkout. A change of harness, model, provider, IDE, process, terminal, or session does not create a new task. Legacy singleton state such as `.forgeloop/work-state.json` is compatibility-only, not the primary modern discovery mechanism.
 1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 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.

package/DOCS_INDEX.md

@@ -16,6 +16,7 @@ integration and guide context. Use this map before editing documentation.
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
 | Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
 | Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
+| Host/orchestrator integration | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) | Serializable phases, transition boundaries, host responsibilities, and no-runtime integration contract |
 | Durable project facts | [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) | Target-specific facts only; no prompts or secrets |
 | Guide selection | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) | Deterministic routing and exclusions |
 | Architecture and safety boundaries | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and [`THREAT_MODEL.md`](./THREAT_MODEL.md) | Design rationale and residual risk |
@@ -31,6 +32,7 @@ integration and guide context. Use this map before editing documentation.
 | **First-time user or developer** | [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) |
 | **AI coding agent / harness** | [`AGENTS.md`](./AGENTS.md) → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) |
 | **Harness integrator** | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) |
+| **External runtime / orchestrator integrator** | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) |
 | **Resuming another tool / session** | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) |
 | **Looking up CLI commands** | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) |
 | **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
@@ -51,6 +53,7 @@ integration and guide context. Use this map before editing documentation.
 - **Find operational copy-paste commands**: [`docs/RECIPES.md`](./docs/RECIPES.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)
 - **Edit documentation safely**: [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md)
 
 `README.md` is intentionally a catalog and quickstart. Do not copy the full

package/ENG/design-code-eng.md

@@ -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.
+- **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,84 @@ 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.
+
+#### External resource discovery workflow
+
+When the needed design capability is not already available in the target project:
+
+1. define the concrete capability first;
+2. search the project's existing components/dependencies before external discovery;
+3. use a curated index such as DesEngs when current alternatives would help;
+4. shortlist at most 2–3 realistic candidates;
+5. inspect each candidate's exact upstream source;
+6. compare license, dependencies, accessibility, performance, compatibility, maintenance, and implementation cost;
+7. choose the smallest compatible option;
+8. do not install anything without the authority already required by ForgeLoop;
+9. record provenance when materially adopting external code or assets.
+
+Bound discovery effort: 2–3 candidates is the strong default; broader research is justified only for a genuinely high-risk architecture decision. External discovery is optional and proportional — it must never become a mandatory browsing gate.
+
+#### Permanent reference admission rule
+
+Do not add every useful external discovery to ForgeLoop's canonical guide. Add a named permanent reference only when it provides a recurring capability, workflow, or quality signal that is materially useful across projects and is not already covered by an existing reference. One-off discoveries remain target-project choices.
+
+A meta-directory such as DesEngs may be used to rediscover current alternatives instead of expanding ForgeLoop into an exhaustive external-tools catalog.
+
+### Design-engineering meta-discovery
+
+- **DesEngs** — https://desengs.com/
+  Optional meta-directory for discovering current design-engineering resources across reading, learning, UI/component exploration, interaction tooling, skills, creative coding, design systems, and implementation references. Use it when a concrete design need is not already satisfied by the target project's design system or a known compatible ForgeLoop reference.
+
+  Treat DesEngs as a discovery index, not as an approval list. For any linked resource that may be materially adopted, inspect the exact upstream source, current license/terms, dependencies, accessibility, browser/platform support, performance cost, maintenance status, and premium/free boundary before use. The license or listing status of DesEngs does not grant reuse rights for the external projects it indexes.
+
+### Optional pattern and asset references
+
+External galleries and asset libraries are reconnaissance tools, not design authority. The target product's requirements, existing design system, accessibility, security, performance budget, and the rules in this guide take precedence.
+
+Before using an external example:
+
+1. identify the design problem it solves;
+2. compare at least two structural options when practical;
+3. choose based on content and interaction needs, not novelty;
+4. rebuild the chosen pattern in the target project's own stack and tokens;
+5. verify accessibility, responsiveness, states, and performance;
+6. verify the current source/license before copying code, prompts, media, or other substantial material.
+
+#### UI pattern reconnaissance
+
+- **VibePrompt** — https://vibeprompts.dev/
+  Optional pattern-vocabulary reference for common UI structures including heroes, pricing, FAQ, onboarding, dashboards, navigation, contact, feature sections, and supporting utility UI. Use it to compare section and interaction structures before implementing, and treat the examples as inspiration and vocabulary, not as canonical ForgeLoop markup. Do not treat Tailwind examples or prompts as canonical ForgeLoop markup; rebuild the selected pattern using the target project's own stack, components, semantic HTML, tokens, accessibility rules, responsive behavior, and performance budget. Verify the source terms before copying any prompt, snippet, or substantial text.
+
+#### Illustration references
+
+- **Kitbitz** — https://kitbitz.art/
+  Optional hand-drawn illustration reference when the selected creative direction genuinely benefits from playful/editorial imagery (education, creative tools, games, maps, community products, illustrated onboarding). Do not make it a default asset source for every site, and do not assume a permanent license status: verify the current first-party license and the exact asset terms before use. Record source, license, purpose, and any required attribution. Prefer SVG when appropriate, optimize delivered assets, provide accessible alternatives, and ensure the page remains understandable if the illustration is unavailable.
+
+#### Editorial strategy reference
+
+- **Elaya Design — Landing Page Design**
+  https://github.com/elayadesign/ai-design-skills/blob/main/skills/landing-page-design/SKILL.md
+
+  Useful as an editorial reference for landing-page strategy, conversion structure, benefit-first copy, objection handling, proof placement, and section-by-section implementation. Its prescriptive visual system (specific fonts, palettes, motion recipes, and navigation styles) is not a ForgeLoop universal rule and does not override this guide or the target project's design system. ForgeLoop's own `NON_BLOCKING`/`BLOCKING` decision classification controls whether the user must be asked anything.
+
 ### 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.
@@ -386,6 +467,49 @@ Adoption workflow:
 
 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/premium-sites-studio-eng.md

@@ -92,6 +92,34 @@ Rules:
 - Identify what must be approved by the client, user, or legal team before writing the interface.
 - Define audience, device, network speed, language, location, and technology as context — not as end-stage details.
 
+### Landing-page specialization
+
+For a true landing page, narrow the brief further:
+
+- identify one offer;
+- identify the primary audience;
+- identify one primary conversion action;
+- define what counts as conversion;
+- determine what visitors already know when they arrive;
+- identify the most important objections;
+- inventory available proof such as product screenshots, documented metrics, case studies, certifications, or real testimonials.
+
+Apply normal ForgeLoop decision classification to missing information. Discover and infer first. A safe, local, reversible design choice is `NON_BLOCKING`: record the assumption and continue. Ask only when a missing fact is genuinely `BLOCKING`, such as real pricing, a regulated claim, a real customer endorsement, a legal guarantee, or external authority.
+
+Choose page structure based on visitor knowledge and conversion friction rather than visual fashion. Useful structural modes include product-led classic, narrative/educational, minimal high-intent, and comparison/alternative-intent.
+
+A common conversion narrative is:
+
+```text
+Hero → problem/context → benefits → how it works → proof → objection handling → final primary CTA
+```
+
+Adapt or remove stages according to the product. This is a decision framework, not a mandatory template.
+
+Lead copy with supported outcomes, then explain features or mechanisms. Keep proof close to the claim it supports. Never invent metrics, testimonials, customer logos, guarantees, certifications, or regulated statements.
+
+For long landing pages, implement one coherent section at a time when practical and verify it before multiplying the pattern across the page.
+
 ## 4. Gate 2 — Content, architecture, and journeys
 
 ### Content inventory

package/ENG/taste-frontend-eng.md

@@ -107,8 +107,9 @@ 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. For React-specific external component
-or motion references, follow the React Bits adoption rules in
+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

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
@@ -1087,6 +1138,29 @@ 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.
 
+### Executable Policy & Autonomy-Preserving Invariants
+
+ForgeLoop enforces executable verification rules (`.forgeloop/policy/rules.json`) that evaluate constraints on code and artifacts.
+
+Autonomy invariant: **zero mandatory configuration, zero mandatory questions, deterministic discovery first, safe defaults second, graceful reduction of enforcement under uncertainty, and explicit configuration only as an optional override.** Uncertainty and corruption are different: uncertainty reduces enforcement where designed (for example, an unknown architecture produces no mandatory architecture question), while a broken trust boundary fails closed (for example, malformed policy produces `E_POLICY_INVALID`).
+
+The enforceable invariants are:
+
+1. **Zero-Interaction Autonomy Invariant**: The default workflow (`init` → `discovery` → `task creation` → `routing` → `execution` → `verification` → `completion`) must run to completion without interactive prompts, interviews, or mandatory user configuration.
+2. **Uncertainty Principle**: "Uncertainty reduces enforcement; uncertainty does not stop execution." When architecture, patterns, or tools cannot be inferred with high confidence, ForgeLoop records `confidence: "LOW"` or `confidence: "UNKNOWN"`, skips unproven rules or treats them as advisory, and proceeds with execution.
+3. **Brownfield Baseline Tolerances**: Existing violations in a repository are fingerprinted (SHA-256) into `.forgeloop/policy/baseline.json`. Baselined debt does not block task completion. Only *new* violations introduced during the task are blocking.
+4. **Monotonic Ratchet-Down**: As legacy debt is resolved, running `forgeloop baseline --update` removes the resolved fingerprints, preventing regression without re-introducing solved violations. It never adds new debt.
+5. **Mutation-Backed Verification**: Rule checkers must prove efficacy against synthetic mutation fixtures via `forgeloop rule-verify`. Expected `FAIL` with checker `FAIL` yields `PROVEN`. Expected `FAIL` with checker `PASS` yields `UNPROVEN` (`CHECK_MUTATION_NOT_DETECTED`).
+6. **Inert Check Graceful Degradation**: Automatically discovered inert checks (no matching files or adapters) degrade to `UNSUPPORTED`/`ADVISORY` with `isInert: true` and no error. Explicit project-configured blocking rules with no effective scope fail with `E_CHECK_INERT` to signal configuration errors.
+7. **Policy Diffing & Drift Detection**: Preflight captures a task policy snapshot (`policy-snapshot.json`). If workspace policy is modified mid-task, `forgeloop policy-status` detects policy drift. Drift is classified into `TIGHTEN` (stricter rules/debt reduction), `NEUTRAL`, `WEAKEN` (relaxed rules/expanded debt), or `UNKNOWN` (legacy snapshot without baseline state). Weakening takes precedence if both occur and blocks completion (`E_POLICY_WEAKENING`).
+8. **Mutation Proof States & Error Correctness**: `verifyRuleMutation` strictly distinguishes `PASS`, `FAIL`, and `ERROR`. Checkers throwing unhandled exceptions produce `observed: ERROR`, `CHECK_MUTATION_EXECUTION_ERROR`, and null `proofDigest`. A checker crash is never treated as proof of detecting a mutation.
+9. **Fail-Closed Policy Availability**: Absence of policy in legacy targets continues with `capability: "NOT_PRESENT"`. Present but corrupt or schema-invalid artifacts fail closed with `E_POLICY_INVALID` (blocking preflight and completion), and evaluation exceptions fail closed with `E_POLICY_EVALUATION_FAILED`.
+10. **Enforced Policy Lock Boundary**: `policy.lock` derives deterministically from effective rules (`built-in rules` + `discovered rules` + `project rules/overrides`) and `baseline`. Modern locks require `algorithm`, `digest`, `rulesDigest`, and `baselineDigest` to participate in integrity validation. `capturedAt` is non-semantic metadata and changes to it alone do not represent a policy change. Lock verification is enforced in `policy-status`, `audit`, and `complete`; unauthorized modifications produce `E_POLICY_LOCK_MISMATCH`.
+11. **Semantic Baseline Snapshots**: Task snapshots retain full semantic baseline entries. Drift diffing classifies fingerprint additions as `WEAKEN` and removals as `TIGHTEN`. Legacy snapshots lacking baseline state classify drift as `UNKNOWN` rather than inventing prior state.
+12. **Baseline Recording Protection During Active Tasks**: Re-recording baseline debt via `baseline --record` is blocked during active policy-bound tasks (`E_BASELINE_RECORD_DURING_ACTIVE_TASK`) to prevent absorbing new violations into legacy debt. `baseline --update` is strictly monotonic; additions trigger `E_BASELINE_EXPANSION`. Explicit operator resets require `--policy-reset-authorized`.
+13. **Semantic Next-Action Policy Recovery**: `forgeloop next` maps policy findings directly to actionable recovery commands (`RESTORE_POLICY`, `REPAIR_CHECKER`, `REPAIR_POLICY`, `REVERIFY_AFTER_POLICY_CHANGE`, `RESTORE_BASELINE`, `CONTINUE_WITH_EXISTING_BASELINE`, `RESOLVE_INERT_CHECK`) rather than collapsing into generic blockers.
+14. **Task Namespacing & Multi-Task Isolation**: Task-aware operations resolve artifacts under `.forgeloop/task-state/<taskKey>/` for the selected task (explicit `--task`, `FORGELOOP_TASK`, or the single active task), so a concurrent task cannot become an implicit source of lifecycle state. With multiple active tasks and no selector, task-aware commands report `E_TASK_AMBIGUOUS` instead of guessing.
+
 ## Evidence-driven correction
 
 ```text

package/LOOP_SYSTEM_DESIGN.md

@@ -24,7 +24,7 @@ The system should use every guide that materially helps the task without loading
 - The loop continues while safe progress is possible. Repetition without new evidence triggers hypothesis reassessment or a blocked result, not infinite retries.
 - Third-party provenance and reuse boundaries remain part of every portable copy.
 - Qwen-MM-Plugins is an optional, task-scoped capability extension: the agent checks native support first, installs the smallest missing capability when needed, and verifies it before use; it is not a package or runtime dependency.
-- Canonical documents are installed under `.forgeloop/kit/`; root native adapters remain small shims and mutable protocol artifacts remain directly under `.forgeloop/`.
+- Canonical documents are installed under `.forgeloop/kit/`; root native adapters remain small discovery shims; project-scoped configuration remains under `.forgeloop/`; and modern mutable task protocol state is isolated under `.forgeloop/task-state/<taskKey>/`.
 - `PREFLIGHT_READY` is a resumable protocol checkpoint reconciled with work state, activation events, fingerprints, and the append-only hash chain.
 
 ## Alternatives considered
@@ -331,6 +331,7 @@ A guide never authorizes installation, publication, deletion, migration, or an e
 - **Missing tool:** use an available equivalent only when it provides compatible evidence; otherwise request approval or report the check as not run.
 - **Missing guide or broken link:** continue only with conservative defaults and disclose the limitation.
 - **Missing credential:** report the blocked capability without exposing or inventing a credential.
+- **Executable policy failure:** present but malformed policy artifacts fail closed and block preflight and completion; policy weakening relative to the task snapshot blocks completion. Canonical invariants and recovery actions are defined in [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md#executable-policy--autonomy-preserving-invariants), with integration obligations in [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
 - **Conflicting instructions:** apply precedence, choose the most conservative interpretation, and record any material decision.
 - **Repeated failure without new evidence:** stop repeating the same action, reassess the hypothesis, and use another diagnostic method.
 - **External or destructive action:** proceed only with explicit authority and an exact validated target.
@@ -367,10 +368,13 @@ directory selected with `--path` when the package is available in the npm
 registry. If it is not available yet, the same commands can run as
 `node src/cli.js ...` from a repository checkout. The CLI maps canonical
 documents into `.forgeloop/kit/`, keeps only native instruction shims at the
-target root, and leaves mutable contract, route, gate, state, event, preflight,
-and receipt artifacts under `.forgeloop/`. Manual copying must preserve that
-target layout; copying package-source root files directly is not equivalent to
-`forgeloop init`.
+target root, and leaves project-scoped configuration under `.forgeloop/` while
+isolating modern mutable task protocol state (contract, route, gate, state,
+event, preflight, and receipt artifacts) under
+`.forgeloop/task-state/<taskKey>/`. Legacy singleton artifacts remain under
+`.forgeloop/` for compatibility and migration only. Manual copying must
+preserve that target layout; copying package-source root files directly is not
+equivalent to `forgeloop init`.
 
 The README explains the file set, activation behavior, current/relative/absolute
 target installation, first-run profile flow, local validation commands, and safe

package/ORCHESTRATOR_INTEGRATION.md

@@ -8,12 +8,13 @@ review primitive without adding that framework to the package.
 
 ```text
 RECEIVED → DISCOVERING → CONTRACT_READY → ROUTED
-                                      ├→ DESIGNING → PLANNED
-                                      └→ PLANNED
+                                       ├→ DESIGNING → PLANNED
+                                       └→ PLANNED
 PLANNED → EXECUTING → VERIFYING
 VERIFYING ├→ DIAGNOSING → CORRECTING → VERIFYING
-          └→ REVIEWING → COMPLETE
-                         └→ VERIFYING when completion is rejected only for evidence
+          └→ REVIEWING ──────────────→ COMPLETE
+                ├→ VERIFYING   evidence-only completion recovery
+                └→ CORRECTING  implementation/review correction required
 Any non-terminal state → BLOCKED when a genuine blocker is evidenced
 ```
 
@@ -50,9 +51,41 @@ Any non-terminal state → BLOCKED when a genuine blocker is evidenced
 | `CORRECTING` | the fix is applied | `VERIFYING` |
 | `VERIFYING` | checks pass | `REVIEWING` |
 | `REVIEWING` | completion is rejected only for evidence | `VERIFYING` |
+| `REVIEWING` | an implementation or review finding requires correction | `CORRECTING` |
 | `REVIEWING` | contract and quality are accepted | `COMPLETE` |
 | `Any non-terminal state` | a genuine external blocker is evidenced | `BLOCKED` |
 
+`BLOCKED` is additionally reachable from any non-terminal, non-`BLOCKED`
+phase when the blocker invariant is satisfied. `WORK_TRANSITIONS` alone is
+therefore not the entire executable transition model; the special `BLOCKED`
+edge is part of the canonical machine semantics.
+
+The exact edge inventory below is generated from the runtime
+(`WORK_PHASES`/`WORK_TRANSITIONS` in `src/core/protocol.js`) and must not be
+edited by hand.
+
+<!-- BEGIN FORGELOOP GENERATED: work-transitions -->
+
+| From | To |
+| --- | --- |
+| `RECEIVED` | `DISCOVERING` |
+| `DISCOVERING` | `CONTRACT_READY` |
+| `CONTRACT_READY` | `ROUTED` |
+| `ROUTED` | `DESIGNING` |
+| `ROUTED` | `PLANNED` |
+| `DESIGNING` | `PLANNED` |
+| `PLANNED` | `EXECUTING` |
+| `EXECUTING` | `VERIFYING` |
+| `VERIFYING` | `DIAGNOSING` |
+| `VERIFYING` | `REVIEWING` |
+| `DIAGNOSING` | `CORRECTING` |
+| `CORRECTING` | `VERIFYING` |
+| `REVIEWING` | `COMPLETE` |
+| `REVIEWING` | `CORRECTING` |
+| `REVIEWING` | `VERIFYING` |
+
+<!-- END FORGELOOP GENERATED: work-transitions -->
+
 The host may skip proportional phases, but it must preserve the state
 invariants and record why a skipped phase was not applicable.
 
@@ -60,12 +93,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/PROTOCOL_INTEGRATION.md

@@ -312,3 +312,16 @@ because the executor changed.
 
 For the practical handoff and multi-tool takeover sequence, see
 [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md).
+
+## Executable Policy Protocol Integration
+
+ForgeLoop integrates executable verification rules directly into the lifecycle:
+
+- **Preflight**: Validates policy capability (`NOT_PRESENT`, `AVAILABLE`, `INVALID`). For `AVAILABLE`, captures effective policy rules and semantic baseline state into `.forgeloop/task-state/<taskKey>/policy-snapshot.json`. If policy artifacts are malformed (`INVALID`), preflight fails closed with `E_POLICY_INVALID`. Snapshot write conflicts fail closed with `E_POLICY_SNAPSHOT_WRITE_FAILED`.
+- **Lock Verification**: Validates `.forgeloop/policy/policy.lock` against effective rules (`built-in` + `discovered` + `project overrides`) and baseline. Requires `algorithm`, `digest`, `rulesDigest`, and `baselineDigest` to match. `capturedAt` is non-semantic metadata. Mismatches trigger `E_POLICY_LOCK_MISMATCH`.
+- **Execution & Verifying**: Evaluates checks with mutation proofing (`rule-verify`). Checkers must cleanly distinguish `PASS`, `FAIL`, and `ERROR` (`CHECK_MUTATION_EXECUTION_ERROR`). Expected mutant failure yields `PROVEN`; false passes yield `UNPROVEN` (`CHECK_MUTATION_NOT_DETECTED`). Unproven or inert checks in discovered rules degrade gracefully without stopping execution.
+- **Completion**: Audits unbaselined violations, policy weakening, and drift. Weakening relative to task snapshot produces `E_POLICY_WEAKENING`. Returns `VALID` when policy integrity is intact and no new unbaselined violations exist.
+- **Autonomy Principle**: Non-interactive execution is preserved. Tools, commands, and validators operate unattended with standard input closed and without interactive prompt dependencies.
+- **Baseline Protection**: Re-recording baseline debt mid-task is rejected with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`; only monotonic ratchet-down is allowed during active tasks (`baseline --update`). Explicit re-recording requires `--policy-reset-authorized`.
+- **Semantic Recovery**: `forgeloop next` maps policy findings directly to actionable recovery actions (`RESTORE_POLICY`, `REPAIR_CHECKER`, `REPAIR_POLICY`, `REVERIFY_AFTER_POLICY_CHANGE`, `RESTORE_BASELINE`, `CONTINUE_WITH_EXISTING_BASELINE`, `RESOLVE_INERT_CHECK`).
+- **Task Scoping**: Task-specific policy snapshots and state live under `.forgeloop/task-state/<taskKey>/` to ensure clean multi-task isolation and cross-harness continuity.