@cassiomc1/forgeloop 1.2.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

@@ -373,6 +373,65 @@ Before materially adopting an external component or interaction:
 
 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.

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

@@ -1138,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.
 

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.

package/README.md

@@ -1,7 +1,7 @@
 # ForgeLoop — Verifiable Engineering Protocol
 
 <p align="center">
-  <img src="./docs/assets/forgeloop-readme-banner.svg" alt="ForgeLoop — Verifiable Engineering Protocol" width="100%">
+  <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" 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)
@@ -96,7 +96,7 @@ Typical local commands are:
 ```bash
 forgeloop task-create --task example-task --claim src --claim tests --json
 forgeloop route --task example-task --work complete-website --surface ui --risk untrusted-input
-forgeloop activate --task example-task
+forgeloop activate
 forgeloop preflight --task example-task --json
 forgeloop next --task example-task --json
 forgeloop advance --task example-task --to PLANNED
@@ -160,6 +160,38 @@ forgeloop complete --task auth-feature --json
 forgeloop task-migrate --json
 ```
 
+### Executable policy verification & brownfield baselines
+
+ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
+
+```bash
+# Discover architecture conventions and candidate rules (read-only unless --write)
+forgeloop policy-discover --json
+
+# Inspect active policy verification status, baselines, and drift
+forgeloop policy-status --json
+
+# Record brownfield legacy debt into baseline to prevent blocking
+forgeloop baseline --record --json
+
+# Monotonically ratchet down resolved technical debt
+forgeloop baseline --update --json
+
+# Prove rule checker efficacy against synthetic mutation fixtures
+forgeloop rule-verify --rule SECURITY.NO_HARDCODED_SECRET --json
+```
+
+A policy-bound task captures its effective rules and semantic baseline in
+`.forgeloop/task-state/<taskKey>/policy-snapshot.json`. The project lock at
+`.forgeloop/policy/policy.lock` protects the effective rules plus baseline and
+must contain matching `algorithm`, `digest`, `rulesDigest`, and `baselineDigest`
+values. `capturedAt` is informational metadata and does not change semantic
+identity. During an active task, `baseline --update` may remove resolved debt,
+but `baseline --record` is blocked unless an operator explicitly supplies
+`--policy-reset-authorized`. Use `forgeloop next --task <id> --json` to receive
+semantic recovery such as `RESTORE_POLICY`, `REPAIR_CHECKER`, or
+`RESTORE_BASELINE` when verification detects drift or corruption.
+
 See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) for architecture details.
 
 ## Architecture flow

package/TERMINOLOGY.md

@@ -25,3 +25,13 @@
 | Execution continuity | Bounded current-task implementation context used to resume the same ForgeLoop task across sessions or harnesses. |
 | Continuity artifact | `.forgeloop/continuity.json`; non-evidence operational context bound to canonical work state. |
 | Continuity reconciliation | Read-only comparison of continuity bindings and path hints against current canonical state and checkout. |
+| Executable policy rule | A structured rule with an automated checker evaluating constraints on code and artifacts. |
+| Policy discovery | Deterministic non-interactive inspection of codebase structure and conventions with confidence levels. |
+| Brownfield baseline | Cryptographically fingerprinted list of pre-existing policy violations tolerated without blocking progress. |
+| Violation fingerprint | SHA-256 hash uniquely identifying a violation by rule, file, and line/content hash. |
+| Monotonic ratchet | Invariant ensuring brownfield baseline debt only decreases as legacy violations are resolved. |
+| Mutation verification | Proving checker capability by asserting failure on intentionally mutated code fixtures. |
+| Proof digest | Cryptographic digest confirming a checker caught a mutation fixture. |
+| Inert check | A verification rule whose check target or scope does not exist or matches 0 files in the codebase. |
+| Policy drift | Divergence between task preflight snapshot policy and current workspace policy. |
+| Policy diff | Semantic classification of policy changes into `TIGHTEN`, `NEUTRAL`, `WEAKEN`, or `UNKNOWN`. |

package/THIRD_PARTY_NOTICES.md

@@ -13,6 +13,22 @@ review the applicable source terms before redistributing such material.
 
 ## Adapted and editorial sources
 
+### Elaya Design — Landing Page Design
+
+- Project:
+  [elayadesign/ai-design-skills](https://github.com/elayadesign/ai-design-skills).
+- Referenced skill:
+  [landing-page-design](https://github.com/elayadesign/ai-design-skills/blob/main/skills/landing-page-design/SKILL.md).
+- License declared by the upstream repository: MIT.
+- Use in this collection: editorial influence for landing-page strategy,
+  conversion structure, proof/objection placement, benefit-first copy, and
+  incremental section-by-section implementation.
+- Boundary: ForgeLoop does not adopt the upstream skill's complete prescriptive
+  visual system as a universal rule, and does not import its intake-question
+  workflow over ForgeLoop's own decision classification. The strategy concepts
+  are paraphrased; if substantial upstream text is copied or adapted in the
+  future, preserve the applicable MIT notice and attribution.
+
 ### A11Y.md
 
 - Project: [fecarrico/A11Y.md](https://github.com/fecarrico/A11Y.md).
@@ -135,6 +151,24 @@ fonts, templates, or other material.
 - [cables.gl](https://cables.gl/): creative-coding and WebGL reference; check
   the tool, exported patches or operators, code, and third-party assets
   separately before distribution.
+- [VibePrompt](https://vibeprompts.dev/): optional UI-pattern and prompt
+  reference for comparing common page/component structures. ForgeLoop does not
+  bundle its prompts or snippets and does not make Tailwind a dependency.
+  Verify the site's current terms and the provenance/license of any prompt,
+  snippet, or substantial material before copying or redistributing it.
+- [Kitbitz](https://kitbitz.art/): optional illustration and visual-asset
+  reference. ForgeLoop does not bundle, mirror, or download its assets. Verify
+  the current first-party license and asset-specific terms before use; record
+  attribution when required and preserve asset provenance in the target
+  project. A catalog listing is not a permanent license statement.
+- [DesEngs](https://desengs.com/) / source
+  [remvze/desengs](https://github.com/remvze/desengs):
+  curated meta-directory for design-engineering resources. The upstream
+  DesEngs repository currently declares MIT for its own software/material
+  covered by that license. ForgeLoop uses the site only as an optional discovery
+  index and does not bundle or mirror its catalog. Each external resource linked
+  by DesEngs retains its own license, terms, authorship, dependencies, and
+  premium/free boundary; inspect the exact upstream source before adoption.
 
 ### Qwen-MM-Plugins
 

package/THREAT_MODEL.md

@@ -43,7 +43,18 @@ remaining trust boundaries and their executable evidence.
 | Recursive npm script dispatch | A recognized npm lifecycle script invokes another npm script, which later invokes an installation-capable resolver (e.g. `test` -> `npm run visual` -> `npx package`) | Recognized npm dispatcher semantics before ForgeLoop process launch | Recursive npm-script resolution with cycle detection, maximum depth (16), lifecycle hook inspection, restart special semantics, and fail-closed behavior when the resolver cannot prove the chain is non-installing | Opaque executables may spawn arbitrary descendants. Full descendant-process attestation requires host-level process controls and is outside this release | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
 | npm invocation rewriting and workspace dispatch | npm configuration flags appear before the subcommand, or npm workspace selectors cause script execution to occur against a package.json different from the ForgeLoop target root | Raw npm argv versus effective npm command and execution context | Canonical npm invocation parsing, effective subcommand extraction, workspace flag detection across the full npm argv, and fail-closed workspace script handling when the selected package.json cannot be proven from the current target | ForgeLoop 0.1.15 intentionally does not implement full npm workspace resolution. Users should execute run-check from the selected workspace target directory | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
 | Unclassified npm Install-Capable Command | The npm security classifier recognizes only a small denylist of package-mutating commands. Another official npm command or alias with install/update/bootstrap semantics falls through as a local package command | Effective npm command semantics versus ForgeLoop's command classifier | Semantic npm command classification with explicit install-capable families, explicit script-dispatch families, a deliberately small non-installing allowlist, and fail-closed behavior for unknown or ambiguous npm commands | Future npm commands are blocked until ForgeLoop explicitly classifies them | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
-| npm Option Value Ambiguity | An unknown npm config option with a separate value appears before the effective subcommand, and a parser misinterprets the option value as the npm subcommand | Raw npm argv and unsupported config syntax | Recognize self-contained `--key=value`, explicitly supported options-with-value, and known boolean options. Unknown long option followed by a non-option token fails closed with `NPM_OPTION_VALUE_AMBIGUOUS` | Unsupported npm config grammar is intentionally rejected rather than guessed | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
+| Policy weakening bypass | An actor weakens complexity or security thresholds mid-task to bypass verification failures | Task policy snapshot (`policy-snapshot.json`) and semantic policy diff | `policy-diff` classifies rule relaxations as `WEAKEN`, preflight snapshots enforce baseline digests, and `complete` blocks on `E_POLICY_WEAKENING` | A project operator with local filesystem access can authoritatively update project rules | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Inert check evasion | An actor relies on an inert or non-matching checker to create false verification pass | Policy engine checker inspection | Scanned file counters and adapter target checks; unproven or inert project rules trigger `E_CHECK_INERT` | Discovered rules gracefully downgrade to advisory without stopping execution | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Baseline debt expansion | An actor expands baseline tolerances during task execution to ignore new violations | Brownfield baseline (`baseline.json`) and violation fingerprints | SHA-256 violation fingerprinting by rule and file content; monotonic ratchet ensures baseline debt only decreases | Operators can intentionally re-record baselines using `forgeloop baseline --record --policy-reset-authorized` | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Unproven mutation checker | A broken or mock checker passes regardless of code correctness | Mutation testing runner (`rule-verify`) | Mutation verification runs checks against synthetic mutant fixtures; failure to catch a mutation yields `CHECK_MUTATION_NOT_DETECTED` and `UNPROVEN` status | Mutation fixtures are maintained for standard built-in adapters | `tests/policy-autonomy.test.js`, `tests/policy-hardening.test.js` |
+| Checker crash interpreted as proof | A broken checker crashes with an exception and is erroneously treated as observing expected failure | Mutation verification runner (`rule-verify`) | Distinguish `ERROR` from `FAIL`; exceptions produce `observed: ERROR`, `CHECK_MUTATION_EXECUTION_ERROR`, and null `proofDigest` | Repaired checker must pass mutation test cleanly | `tests/policy-hardening.test.js` |
+| Policy corruption bypass | Malformed policy artifacts cause runtime errors that are silently ignored to bypass checks | Fail-closed policy evaluation in `audit` and `complete` | Explicit capability classification (`NOT_PRESENT`, `AVAILABLE`, `INVALID`); corrupt artifacts fail closed with `E_POLICY_INVALID` or `E_POLICY_EVALUATION_FAILED` | Absent policy in legacy targets remains compatible without blocking | `tests/policy-hardening.test.js` |
+| Partial initialization authority | Manifest is committed before executable-policy bootstrap completes, so a repository appears initialized while `discovery.json`/`baseline.json`/`policy.lock` are partial or absent | Manifest commit boundary during `forgeloop init` | Manifest-last commit authority: policy artifacts are written and verified (`detectPolicyCapability` = `AVAILABLE`, `verifyPolicyLock` = `VALID`) before the manifest is written; any bootstrap failure raises `E_POLICY_INITIALIZATION_FAILED` with no committed manifest; retry reconciles already-correct files and fails with a deterministic conflict on unowned divergent content; `dry-run` performs no writes | A trusted operator can still deliberately edit artifacts after initialization | `tests/init-policy.test.js` |
+| Lock regeneration or subdigest tampering | An actor modifies rules or baseline, omits subdigests, or regenerates `policy.lock` to hide tampering | Effective policy lock verification (`verifyPolicyLock`) | Lock derives deterministically from effective rules + baseline. Schema-invalid lock artifacts (malformed JSON or missing required fields such as `rulesDigest`/`baselineDigest`) fail closed with `E_POLICY_INVALID`; schema-valid locks whose semantic digest components (`algorithm`, `digest`, `rulesDigest`, `baselineDigest`) no longer match effective policy state fail with `E_POLICY_LOCK_MISMATCH` before any relocking. Changing only `capturedAt` does not change semantic identity | Explicit update commands (`policy-discover --write`, `baseline`) update lock after authorization | `tests/policy-hardening.test.js` |
+| Baseline re-record bypass | An actor uses `baseline --record` during an active task to convert newly introduced violations into tolerated debt | Active task baseline protection in `runBaseline` | `baseline --record` is rejected during active policy-bound tasks with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`; only monotonic `--update` is permitted | Explicit `--policy-reset-authorized` flag required for intentional operator resets | `tests/policy-hardening.test.js` |
+| Legacy snapshot semantic confusion | A legacy task snapshot lacking baseline state is assumed to have empty baseline, creating false `WEAKEN` drift | Semantic baseline snapshotting in `policy-snapshot.json` | Snapshots retain full semantic baseline entries; snapshots lacking baseline state classify drift as `UNKNOWN` rather than inventing state | Modern tasks retain semantic baseline entries for exact diff | `tests/policy-hardening.test.js` |
+| Cross-task state confusion | Concurrent processes or alternative harnesses mutate or read the wrong task's state in a multi-task workspace | Task-scoped isolation in `.forgeloop/task-state/<taskKey>/` | Deterministic SHA-256 task directory namespacing, explicit `--task` / `FORGELOOP_TASK` selectors, file-level mutex locking (`.lock`), and claim overlap detection in `task-create` | Tasks must declare non-overlapping write claims or operate in isolated worktrees | `tests/task-namespace.test.js`, `tests/task-scope.test.js` |
+| Modern namespace descriptor deletion | Corruption or an attacker removes `task.json` from a modern task namespace (leaving contract/work-state/receipt/events), the resolver ignores the namespace, and stale legacy singleton state becomes authoritative | Descriptor boundary between modern task namespaces and the legacy singleton | Descriptor-less 64-hex directories are classified by contents: directories containing modern task artifacts (or empty directories) fail closed with `E_TASK_DESCRIPTOR_INVALID`; only directories containing exclusively the explicitly recognized legacy-incidental artifact (`policy-snapshot.json`) are ignored; `resolveTaskContext` fails closed when all namespaces are corrupt | A separately privileged process can rewrite task-state directories after validation | `tests/validate-receipt-task.test.js` |
 
 ## Boundary rules