@cassiomc1/forgeloop 0.1.11 → 0.1.13

package/PROTOCOL_INTEGRATION.md

@@ -0,0 +1,199 @@
+# Protocol Integration
+
+ForgeLoop is a portable, project-scoped engineering protocol. It is vendor-neutral
+and is not tied to a specific model, provider, agent product, IDE, or orchestration runtime.
+
+The protocol becomes applicable because a project activates ForgeLoop, not because
+an execution environment appears in a compatibility list.
+
+<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
+
+## Universal applicability
+
+If the active execution environment discovers a ForgeLoop project adapter,
+the canonical ForgeLoop protocol applies to work performed in that project.
+
+```text
+PROJECT HAS FORGELOOP ADAPTER
++
+RUNTIME DISCOVERS IT
++
+REQUIRED LOCAL CAPABILITIES ARE AVAILABLE
+=
+FORGELOOP APPLIES
+```
+
+An execution environment that has not been previously tested is
+`CONFORMANCE_UNVERIFIED`, not unsupported and not exempt from the protocol.
+
+Capabilities determine how much of ForgeLoop can be executed. Brand names do not.
+
+### Interpretation rules
+
+```text
+INVALID:
+"I am not a named ForgeLoop integration, therefore ForgeLoop does not apply."
+"I will follow ForgeLoop only in spirit because my harness is not documented."
+
+VALID:
+"I discovered the ForgeLoop project adapter. ForgeLoop applies.
+My current runtime may have unverified or limited capabilities, which I will evaluate."
+```
+
+## Integration levels
+
+Execution environments integrate with ForgeLoop by capability:
+
+### Level 1 — `INSTRUCTION_DISCOVERED`
+
+The environment has automatically or explicitly loaded a project-local ForgeLoop
+adapter (such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`,
+`.github/copilot-instructions.md`, or manual bootstrap).
+
+### Level 2 — `PROTOCOL_CAPABLE`
+
+The environment possesses the necessary local capabilities:
+
+- Read project files.
+- Write project-local files.
+- Execute local commands.
+- Invoke the project-local ForgeLoop CLI.
+- Preserve project state across lifecycle transitions.
+
+When these are available, the environment executes the complete ForgeLoop lifecycle.
+
+### Level 3 — `PROTOCOL_LIMITED`
+
+The environment discovered ForgeLoop but lacks one or more required local
+capabilities (for example, no command execution or no write access).
+
+ForgeLoop **still applies**, but the runtime must:
+
+- Fail closed for the affected lifecycle dimension.
+- Report the missing capability explicitly.
+- Never simulate missing capabilities.
+- Never manually fabricate protocol-owned state.
+- Never claim validator-backed completion.
+
+### Level 4 — `CONFORMANCE_VERIFIED`
+
+A specific runtime, model, version, environment, and configuration has completed a
+recorded blind conformance scenario under standard protocol verification.
+
+Conformance verification is **evidence of tested interoperability**; it is
+never an eligibility gate or allowlist for protocol adoption.
+
+## Discovery surfaces
+
+ForgeLoop provides project-local shims for common instruction-discovery mechanisms:
+
+- `AGENTS.md`: Standard discovery surface recognized by multiple AI coding tools and developers.
+- `CLAUDE.md`: Discovery surface for Claude Code.
+- `.cursor/rules/project-loop.mdc`: MDC rule format for Cursor.
+- `.github/copilot-instructions.md`: Repository instructions for GitHub Copilot.
+
+These files are discovery aliases. They all point to the same canonical project
+protocol in `.forgeloop/kit/LOOP_ENGINEERING.md` and `.forgeloop/kit/PROTOCOL_INTEGRATION.md`.
+They do not define separate ForgeLoop implementations.
+
+### Generic and manual bootstrap
+
+For environments, internal enterprise agents, custom harnesses, or developer-operated
+workflows that do not automatically discover one of the default files:
+
+1. Read `.forgeloop/kit/LOOP_ENGINEERING.md`.
+2. Read `.forgeloop/kit/PROTOCOL_INTEGRATION.md`.
+3. Resolve the project-local ForgeLoop CLI.
+4. Execute the contract, route, preflight, and lifecycle workflow.
+
+A developer or custom automation can execute ForgeLoop identically to an AI agent.
+
+## CLI resolution policy
+
+Lifecycle-owned protocol state must be managed through the project-local ForgeLoop CLI:
+
+1. Project-local `node_modules/.bin/forgeloop`
+2. Package manager local execution (e.g. `npx --no-install forgeloop` or equivalent)
+3. Direct package CLI entry point (`node src/cli.js`)
+4. Verified global `forgeloop` matching the installed package version
+
+Do not automatically download a different version during a reproducible run.
+The resolved CLI must match the installed project's package identity.
+
+## Protocol-owned state and no-simulation policy
+
+The following protocol artifacts are strictly owned by ForgeLoop:
+
+- `.forgeloop/preflight.json`
+- `.forgeloop/work-state.json`
+- `.forgeloop/events.ndjson`
+- `.forgeloop/execution-receipt.json`
+- Canonical check, evidence, and terminal-result state
+
+If the required CLI or API capability cannot be resolved:
+
+- **Do not** fabricate lifecycle state manually.
+- **Do not** synthesize event history.
+- **Do not** manually assign `COMPLETE`.
+- **Do not** construct a fake execution receipt.
+- **Do not** rewrite `events.ndjson` to simulate chronology.
+
+Report the corresponding ForgeLoop dimension as `NOT_VERIFIED` / `E_FORGELOOP_CLI_UNAVAILABLE`.
+
+## Missing tool capability
+
+A missing tool is a capability gap, not installation authority.
+
+If an expected verifier, browser tool, linter, analyzer, or test dependency is
+not already available:
+
+- use a suitable existing local equivalent when possible;
+- otherwise request authority if installation is necessary and allowed;
+- otherwise report the affected verification dimension as not verified with
+  `E_VERIFICATION_TOOL_UNAVAILABLE`.
+
+Never convert `PROTOCOL_LIMITED` into environmental mutation by implicitly
+installing a package.
+
+## Optional capability extensions
+
+The installed loop directs the active actor to inspect native model and harness
+capabilities. When a task requires a missing capability (e.g. multimodal vision),
+the actor may install the smallest task-scoped capability (such as `Qwen-MM-Plugins`)
+through native mechanisms or upstream installers, then verify it before use.
+
+API credentials, system packages, and unrelated environment changes remain
+separately gated.
+
+## Delegation scope
+
+Delegation is optional.
+
+A run that contains no delegation events, no delegated task references, and no
+delegation artifacts is a valid single-actor run.
+
+Missing delegation artifacts must not make such a run incomplete. For a purely
+local single-actor lifecycle, the delegation dimension is `NOT_APPLICABLE`.
+
+Once delegation is observed in canonical state, receipt, or event history, the
+required delegation artifacts become mandatory.
+
+## Instruction precedence
+
+When multiple instruction layers exist, follow standard precedence:
+
+1. Platform, sandbox, and system security rules.
+2. Direct user instructions in the latest prompt.
+3. Target project-specific rules and instructions.
+4. ForgeLoop project protocol (`LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`).
+5. Activated domain guides (`GUIDE_ROUTER.md` → `ENG/*.md`).
+6. Technical defaults and safe assumptions.
+
+The absence of an environment's name from documentation is never a precedence conflict.
+
+## External workflow interaction
+
+External planning, interview, or review workflows (such as `/grill-me`, `/plan`, or IDE
+review gates) may assist in clarifying requirements, but they must not silently
+redefine ForgeLoop `NON_BLOCKING` decisions as `BLOCKING` in autonomous mode.
+Consult `LOOP_ENGINEERING.md#external-workflow-interaction` for the complete boundary.

package/QUALITY_SCORECARD.md

@@ -80,7 +80,7 @@ are both present:
 | Hidden kit layout | `src/core/target-layout.js`, safe init/update migration, manifest layout version, native shims, and profile resolver | `tests/hidden-layout.test.js`, package and compatibility tests |
 | Contextual frontend taste | `ENG/taste-frontend-eng.md`, router metadata, attribution, and design/accessibility precedence | `tests/taste-guide.test.js`, route fixtures |
 | Pre-contract autonomy — structural | `LOOP_ENGINEERING.md`, `src/core/decision-classification.js`, `src/core/workflow-compatibility.js`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursor/rules/project-loop.mdc` | `tests/decision-classification.test.js`, `tests/workflow-compatibility.test.js`, `tests/autonomy-policy.test.js`, `tests/preflight.test.js` |
-| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `AGENT_COMPATIBILITY.md`, `src/core/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
+| External workflow compatibility — structural | `LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `src/core/workflow-compatibility.js`, and sixth-run harness metadata rule | `tests/workflow-compatibility.test.js`, `conformance/README.md` |
 | Instruction-conflict handling — structural | Canonical source-attribution and `WORKFLOW_CONFLICT` policy in `LOOP_ENGINEERING.md` plus adapter references | `tests/autonomy-policy.test.js`, `tests/workflow-compatibility.test.js` |
 | Autonomous-mode precedence — structural | Autonomous/interactive mode contract and harness exclusion metadata | `tests/workflow-compatibility.test.js`, `tests/conformance-scenarios.test.js` |
 | Pre-contract autonomy — cross-agent live robustness | Prior third blind-run result, `conformance/runs/2026-08-13-codex-fourth-live.md`, preserved fifth-run report `conformance/runs/2026-08-13-codex-fifth-live.md`, and the exact blind request | `tests/conformance-scenarios.test.js`; sixth run is not started until mandatory approval is excluded |

package/README.md

@@ -1,25 +1,18 @@
-# ForgeLoop — Instruction Guides for AI Agents
+# ForgeLoop — Verifiable Engineering Protocol
 
 [![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)
 
-An English-only collection of operational guides for AI agents and developers.
-It covers product strategy, code, testing, security, performance,
-accessibility, design, and web games across web, mobile, and desktop projects.
+ForgeLoop is a portable, verifiable engineering protocol for AI-assisted development and developer workflows.
 
-The files are Markdown and can be used as references, as a foundation for
-`AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, and
-`.github/copilot-instructions.md`. The supported-agent contract is documented
-in [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md). Adopt only the guides
-relevant to the target project.
+It is project-scoped, capability-based, and vendor-neutral. It turns intent into contract-driven execution with deterministic routing, resumable state, evidence-backed verification, recovery, and validator-backed completion.
 
-ForgeLoop is the portable, evidence-first loop that connects deterministic
-routing, checkpointed state, observable evidence, conformance, and delegation
-for compatible agent harnesses.
+ForgeLoop does not depend on a specific model, provider, agent product, IDE, or orchestration runtime.
 
-The npm package also ships the local `forgeloop` CLI. In a target project it
-installs canonical documents under `.forgeloop/kit/`, keeps only small native
-discovery shims at the root, and stores mutable protocol artifacts under
-`.forgeloop/`.
+The repository also provides an English-only collection of operational engineering guides covering product strategy, clean code, testing, security, performance, accessibility, visual design, and web games across web, mobile, and desktop projects.
+
+Project-local discovery surfaces (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`) and manual bootstrap paths delegate to the same canonical protocol in `.forgeloop/kit/`. The capability levels and integration contract are documented in [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md). Adopt only the guides relevant to the target project.
+
+The npm package also ships the local `forgeloop` CLI. In a target project it installs canonical documents under `.forgeloop/kit/`, keeps only small native discovery shims at the root, and stores mutable protocol artifacts under `.forgeloop/`.
 
 ## Catalog
 
@@ -54,141 +47,13 @@ target).
 The canonical system map, including the routing/state/evidence architecture, is
 in [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
 
-```mermaid
-flowchart TB
-  subgraph INIT["1. Bootstrap & Adaptation"]
-    root["FORGELOOP"]
-    entry["native adapters<br/>+ .forgeloop/kit/"]
-    migration{"target<br/>layout"}
-    plan["validate paths<br/>+ build plan"]
-    hidden["write hidden<br/>kit"]
-    verified["verify hidden<br/>bytes"]
-    authority["atomic manifest<br/>authority switch"]
-    cleanup["hash-checked<br/>legacy cleanup"]
-    recovered["healthy or<br/>recoverable"]
-    incomplete["doctor:<br/>E_MIGRATION_INCOMPLETE"]
-    retry["update + retry<br/>owned cleanup"]
-  end
-
-  subgraph CONTRACT_ROUTING["2. Discovery, Contract & Routing"]
-    discovery["discovery +<br/>project profile"]
-    contract["current<br/>contract"]
-    routing["deterministic<br/>route"]
-    gates["required<br/>gates"]
-    preflight["preflight"]
-    ready["PREFLIGHT_READY"]
-    blocker["repair /<br/>blocker"]
-  end
-
-  subgraph EXECUTION_LOOP["3. Execution & Verification Loop"]
-    state["work-state<br/>checkpoint"]
-    events["append-only<br/>event ledger"]
-    lifecycle["PLANNED → EXECUTING<br/>→ VERIFYING"]
-    prepare["prepare<br/>completion receipt"]
-    checks["checks + structured<br/>evidence"]
-    readiness{"canonical evidence<br/>readiness"}
-    review["REVIEWING<br/>cycle N"]
-    diagnose["DIAGNOSING →<br/>CORRECTING"]
-    terminal_result["record-terminal-result<br/>(publication / production)"]
-    complete["complete<br/>validator"]
-    terminal["COMPLETE"]
-    rejected["COMPLETION_REJECTED<br/>(cycle N + 1)"]
-    receipt["updated execution<br/>receipt"]
-  end
-
-  subgraph AUDIT_CONFORMANCE["4. Freshness, Audit & Conformance"]
-    freshness["freshness<br/>fingerprints"]
-    conformance["validate-protocol<br/>/ conformance"]
-    audit["audit +<br/>validate-protocol"]
-    verdict["VALID / INCOMPLETE /<br/>STALE / INCONSISTENT / INVALID"]
-    delegation["optional bundle /<br/>delegation"]
-    handoff["handoff to<br/>compatible harness"]
-  end
-
-  root --> entry
-  entry --> migration
-  migration -->|legacy v1| plan
-  plan --> hidden
-  hidden --> verified
-  verified --> authority
-  authority --> cleanup
-  cleanup --> recovered
-  hidden -. interruption .-> incomplete
-  verified -. interruption .-> incomplete
-  authority -. interruption .-> incomplete
-  cleanup -. interruption .-> incomplete
-  migration -->|layout v2| retry
-  incomplete --> retry
-
-  entry --> discovery
-  discovery --> contract
-  contract --> routing
-  contract --> preflight
-  routing --> preflight
-  gates --> preflight
-  preflight -->|READY| ready
-  preflight -->|BLOCKED| blocker
-
-  ready --> state
-  ready --> events
-  state --> lifecycle
-  lifecycle --> prepare
-  prepare --> checks
-  checks --> readiness
-  readiness -->|covered| review
-  readiness -->|failed / blocked| diagnose
-  diagnose --> checks
-  review --> complete
-  review --> terminal_result
-  terminal_result --> complete
-  complete -->|VALID| terminal
-  complete -->|evidence-only rejection| rejected
-  rejected --> prepare
-  checks --> receipt
-  terminal_result --> receipt
-
-  contract --> freshness
-  routing --> freshness
-  state --> freshness
-  checks --> freshness
-  routing --> conformance
-  state --> conformance
-  receipt --> conformance
-  freshness --> conformance
-  conformance --> verdict
-  complete --> audit
-  events --> audit
-  audit --> verdict
-
-  routing --> delegation
-  checks --> delegation
-  delegation --> handoff
-  verdict --> handoff
-  blocker --> handoff
-
-  classDef root fill:#08090C,stroke:#6E6AF5,stroke-width:3px,color:#EDEEF0;
-  classDef entry fill:#101218,stroke:#3EDBB8,stroke-width:2px,color:#EDEEF0;
-  classDef migration fill:#0F766E,stroke:#5EEAD4,stroke-width:2px,color:#FFFFFF;
-  classDef routing fill:#4F46E5,stroke:#A5B4FC,stroke-width:2px,color:#FFFFFF;
-  classDef state fill:#373A46,stroke:#A1A1AA,stroke-width:2px,color:#FFFFFF;
-  classDef evidence fill:#3EDBB8,stroke:#99F6E4,stroke-width:2px,color:#08090C;
-  classDef fact fill:#181B24,stroke:#6E6AF5,stroke-width:1px,color:#EDEEF0;
-  classDef gate fill:#3730A3,stroke:#A5B4FC,stroke-width:2px,color:#FFFFFF;
-  classDef result fill:#C9A876,stroke:#F5D9A6,stroke-width:2px,color:#08090C;
-  classDef harness fill:#101218,stroke:#3EDBB8,stroke-width:2px,color:#EDEEF0;
-
-  class root root;
-  class entry,discovery,delegation entry;
-  class migration,plan,hidden,verified,authority,cleanup,recovered,retry,incomplete migration;
-  class routing,preflight,ready routing;
-  class state,events,lifecycle,review state;
-  class checks,readiness,receipt,complete,audit,terminal_result evidence;
-  class diagnose,rejected,gates,blocker gate;
-  class terminal,verdict result;
-  class contract,freshness,conformance fact;
-  class handoff harness;
-  linkStyle default stroke:#8A8F98,stroke-width:1.5px;
-```
+<p align="center">
+  <img
+    src="./docs/assets/forgeloop-flow.svg"
+    alt="ForgeLoop evidence-first engineering flow"
+    width="100%"
+  />
+</p>
 
 Equivalent reading for text-only environments: adapters load the canonical kit;
 an older target follows validate paths → write hidden files → verify their bytes
@@ -215,11 +80,13 @@ Request → discovery → profile → routing → plan → execution
               └ evidence-only rejection / next cycle
 ```
 
-Thin native adapters support Codex, Claude Code, Cursor, and GitHub Copilot.
-Antigravity, OpenCode, Hermes, Pi, Command Code, and Freebuff use the shared
-`AGENTS.md` entry point. All ten agents delegate to the same canonical
-documents; see [`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md) for the
-official sources and precedence notes.
+ForgeLoop is project-scoped, capability-based, and vendor-neutral.
+
+Project-local discovery surfaces delegate to the same canonical ForgeLoop protocol. Execution environments that automatically discover one of those instruction surfaces can use it directly, while custom runtimes, automation systems, and developer workflows can use the manual bootstrap path.
+
+Capabilities determine execution. Runtime names do not determine protocol applicability.
+
+See [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) for discovery, capability levels, degradation rules, and precedence.
 
 ### Migration recovery and release freeze
 
@@ -242,12 +109,92 @@ The regression suite injects failures at these boundaries and verifies that
 owned cleanup. The frozen published installation under
 [`tests/fixtures/legacy-0.1.6/`](./tests/fixtures/legacy-0.1.6/) is derived
 from the real npm tarball, includes provenance and digests, and is copied into
-The current published release is `@cassiomc1/forgeloop@0.1.11`.
-Earlier `0.1.8`, `0.1.9`, and `0.1.10` references are historical; never move
-their tags or `v0.1.10`. Version `0.1.11` adds canonical evidence readiness,
-requirement-specific terminal result recording, legal repeated verification
-cycles, future-result and compound-evidence safeguards, and lifecycle-ledger
-divergence detection.
+The current published release is `@cassiomc1/forgeloop@0.1.13`.
+Earlier `0.1.8`, `0.1.9`, `0.1.10`, `0.1.11`, and `0.1.12` references are historical; never move
+their tags or `v0.1.10`. Version `0.1.13` enforces the missing verification tool
+policy, conditional single-actor delegation validation, and a universal
+vendor-neutral engineering protocol positioning.
+
+## How to prompt ForgeLoop
+
+You do not need a perfect prompt to use ForgeLoop.
+
+Describe the outcome you want. ForgeLoop is designed to structure the execution around that request: resolve safe ambiguities, create an execution contract, route the relevant guides, satisfy gates, run preflight checks, implement, verify, correct, and repeat until the work is complete.
+
+> **Don't engineer the perfect prompt. Define the outcome and let ForgeLoop engineer the feedback loop.**
+
+### Minimal
+
+A short request should be enough for ordinary work:
+
+```text
+Create a premium website for a law firm.
+```
+
+### Recommended
+
+Add the important outcome and product constraints:
+
+```text
+Create a premium website for a law firm.
+
+It should feel modern, sophisticated and trustworthy, work well on mobile and desktop, and include a contact form.
+```
+
+### Structured
+
+For larger or more constrained tasks, you can optionally use a lightweight task brief:
+
+```text
+Build: Premium law firm website
+
+Goal:
+Create a modern, sophisticated and trustworthy experience.
+
+Requirements:
+- Responsive on mobile and desktop
+- Accessible navigation
+- Contact form
+- Premium visual design
+- Good performance
+
+Done when:
+- The implementation is complete
+- Required verification passes
+- Mobile and desktop layouts are verified
+- The contact form works
+```
+
+The structured format is optional. It gives ForgeLoop more explicit constraints and success criteria, but it should not be necessary for ordinary tasks.
+
+### What not to put in the prompt
+
+Avoid recreating the ForgeLoop process inside the prompt:
+
+```text
+First analyze the task.
+Then create a plan.
+Then inspect the files.
+Then choose the guides.
+Then implement.
+Then run tests.
+If tests fail, fix them.
+Then review everything.
+Then produce a report.
+```
+
+That workflow belongs to ForgeLoop.
+
+Your prompt should primarily describe:
+
+```text
+what you want
+important requirements
+real constraints
+observable success conditions
+```
+
+ForgeLoop should determine how to execute and verify the work.
 
 ### Use with npm
 
@@ -256,12 +203,12 @@ project without overwriting local instructions. When the package is available
 in the npm registry, use the commands below; otherwise use the repository
 checkout fallback.
 
-The current published release is `@cassiomc1/forgeloop@0.1.11`.
+The current published release is `@cassiomc1/forgeloop@0.1.13`.
 Pin this version when a reproducible blind run or release-identity check is
 required:
 
 ```bash
-npx @cassiomc1/forgeloop@0.1.11 --version
+npx @cassiomc1/forgeloop@0.1.13 --version
 npx @cassiomc1/forgeloop init
 npx @cassiomc1/forgeloop doctor
 npx @cassiomc1/forgeloop update
@@ -358,11 +305,13 @@ cross-artifact relationships plus the same derived freshness classification
 used by `inspect` and `status`. Supply `--contract-file` to compare the saved
 contract fingerprint with the current contract; omitting it leaves contract
 freshness as `NOT_VERIFIED` and a complete artifact set requires revalidation.
-When delegation is in scope, also supply the matching repeated
-`--task-brief <path>` and `--delegated-result <path>` inputs. Without those
-inputs it reports `INCOMPLETE` with
-`task briefs and delegated results were not supplied`; that classification is
-separate from a local `complete --json` result of `VALID`.
+Delegation artifacts are required only when delegation is present in the
+canonical execution history or explicitly supplied as part of a delegated run.
+For a purely local single-actor lifecycle, the delegation dimension is
+`NOT_APPLICABLE` and does not require task briefs or delegated results. When
+delegation is in scope, also supply the matching repeated
+`--task-brief <path>` and `--delegated-result <path>` inputs; omitting them in a
+delegated run reports `INCOMPLETE`.
 It returns `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or `INVALID` with
 exact invariant codes and derived stale reasons. The persisted
 `.forgeloop/work-state.json` schema is unchanged: `status`, `stale`, and `fresh`
@@ -371,7 +320,7 @@ are never stored in that file. Status precedence is `INVALID` > `INCONSISTENT`
 All protocol-support commands are local and offline-capable by default; the
 package sends no telemetry and has no central trace service.
 Capability gaps and inline/non-Git degraded mode are defined in
-[`AGENT_COMPATIBILITY.md`](./AGENT_COMPATIBILITY.md); they are reported as
+[`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md); they are reported as
 limitations rather than treated as silent successes.
 
 ### Live conformance modes
@@ -526,6 +475,7 @@ must remain thin. The resulting target layout is:
 AGENTS.md
 CLAUDE.md
 .forgeloop/.gitignore
+.forgeloop/kit/PROTOCOL_INTEGRATION.md
 .forgeloop/kit/AGENT_COMPATIBILITY.md
 .forgeloop/kit/LOOP_ENGINEERING.md
 .forgeloop/kit/GUIDE_ROUTER.md
@@ -577,7 +527,7 @@ commands. A generic response that does not mention the loop, router, or sources
 indicates that the adapter was not loaded.
 
 After installation, start the preferred agent from the target project
-directory. Use `AGENT_COMPATIBILITY.md` to confirm which file it should load and
+directory. Use `PROTOCOL_INTEGRATION.md` to confirm which file it should load and
 which native entry point is expected. A live agent session is not required for
 package installation or its automated tests.
 
@@ -618,8 +568,8 @@ installed automatically.
 
 ## Optional multimodal capabilities
 
-[Qwen-MM-Plugins](https://github.com/QwenLM/Qwen-MM-Plugins) can extend a
-supported agent harness with skills and optional MCP servers. Before using a
+[Qwen-MM-Plugins](https://github.com/QwenLM/Qwen-MM-Plugins) can extend an
+execution environment with skills and optional MCP servers. Before using a
 multimodal or media operation, the agent checks the model and harness for a
 callable native capability. If the task requires a missing keyless capability,
 the agent installs only the smallest matching `qwen-mm-plugins-<cap>` capability
@@ -667,7 +617,8 @@ adoption. Local rendering requires Node.js 22+ and FFmpeg.
 .
 ├── AGENTS.md                       # shared Codex-compatible entry point
 ├── CLAUDE.md                       # Claude Code entry point
-├── AGENT_COMPATIBILITY.md          # supported agents and official sources
+├── PROTOCOL_INTEGRATION.md         # vendor-neutral capability integration
+├── AGENT_COMPATIBILITY.md          # compatibility alias
 ├── LOOP_ENGINEERING.md             # canonical operating cycle
 ├── GUIDE_ROUTER.md                 # contextual guide selection
 ├── PROJECT_PROFILE.md              # source profile (target copy is under .forgeloop/kit/)

package/TERMINOLOGY.md

@@ -19,3 +19,5 @@
 | Evidence kind | One of `OBSERVED`, `INFERRED`, `NOT_VERIFIED`, or `BLOCKED`; evidence never upgrades an unverified claim by itself. |
 | Required artifact | A checkpoint-recorded relative path and SHA-256 hash that must still match before resume. |
 | Conformance | Relationship validation across route, state, receipt, task brief, and delegated-result artifacts. |
+| Universal applicability | ForgeLoop applies whenever an execution environment discovers a project adapter, regardless of model, provider, agent, IDE, or tool name. |
+| Integration level | The capability tier of an execution environment (`INSTRUCTION_DISCOVERED`, `PROTOCOL_CAPABLE`, `PROTOCOL_LIMITED`, `CONFORMANCE_VERIFIED`). |

package/THREAT_MODEL.md

@@ -30,6 +30,11 @@ remaining trust boundaries and their executable evidence.
 | Protocol-version confusion | Old/future artifacts are silently reinterpreted | Cross-artifact protocol boundary | Explicit v1 checks and conformance errors for unsupported or mixed versions | A future protocol needs a deliberate migration implementation | `tests/conformance.test.js`, `tests/fixtures/protocol/invalid/` |
 | Dependency-cycle denial of service | Coordination cannot make progress or spends unbounded work | Delegation dependency graph | Deterministic DFS cycle detection, unknown-reference rejection, and bounded JSON | A caller can still submit many valid tasks; host-level quotas remain external | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
 | Oversized JSON artifacts | Excess CPU or memory during validation | Any untrusted JSON artifact | Byte, depth, array, object-key, and string limits before semantic traversal | Limits are conservative defaults, not a complete resource scheduler | `tests/security-limits.test.js`, `src/core/json-safety.js` |
+| Runtime self-exemption | An execution environment discovers ForgeLoop but decides that the protocol does not apply because the environment is not named in documentation | Project adapter discovery and runtime interpretation | Universal applicability marker, capability-based integration, explicit unknown-runtime rule, no finite eligibility allowlist | A non-compliant runtime can ignore project instructions entirely | `tests/discovery-surfaces.test.js`, `tests/test_workflow_policy.py` |
+| Blind oracle exposure | The system under test reads expected route/gate/evidence answers from the installed package and contaminates a blind conformance run | Published npm package and agent-readable target workspace | Exclude conformance oracles from npm package, tarball leak scan in `pack:check`, external harness-owned oracle | A misconfigured external harness may still copy oracle material into target | `tests/package.test.js`, `conformance/README.md` |
+| Lifecycle simulation after CLI resolution failure | A runtime manually writes protocol-owned JSON and falsely claims conformance when the CLI is unresolved | Lifecycle-owned protocol state and CLI availability | CLI-owned artifact policy, universal adapter prohibition, validator-backed completion, append-only ledger hash chain | A privileged local process can tamper with local files; ForgeLoop detects consistency, not remote attestation | `tests/discovery-surfaces.test.js`, `tests/lifecycle.test.js`, `LOOP_ENGINEERING.md` |
+| Unauthorized verification dependency installation | The active actor mutates the environment by downloading or installing a missing checker merely to satisfy verification | Verification capability discovery and installation authority | Missing verification tool policy, non-installing resolution first, explicit installation authority, equivalent-check fallback, NOT_VERIFIED degradation | A privileged external process may still install tools outside ForgeLoop's control | `tests/verification-capability.test.js`, `tests/discovery-surfaces.test.js`, `LOOP_ENGINEERING.md` |
+| False delegation requirement | A valid single-actor run is incorrectly reported as incomplete because a validator demands artifacts for delegation that never occurred | Validator delegation scope resolution | Canonical delegationIsInScope predicate, conditional delegation validation in validateTaskArtifactSet and validate-protocol | Malformed or externally injected artifacts may require INCONSISTENT classification | `tests/conformance.test.js`, `tests/validate-protocol-cli.test.js` |
 
 ## Boundary rules
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "0.1.11",
-  "description": "Portable, verifiable instruction kit for AI agents and developers",
+  "version": "0.1.13",
+  "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cassiomc1/forgeloop.git"
@@ -22,12 +22,12 @@
     "src",
     "ENG",
     "schemas",
-    "conformance",
     ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
     "GUIDE_ROUTER.md",
     "LOOP_ENGINEERING.md",
+    "PROTOCOL_INTEGRATION.md",
     "LOOP_SYSTEM_DESIGN.md",
     "QUALITY_SCORECARD.md",
     "TERMINOLOGY.md",
@@ -48,6 +48,7 @@
   "scripts": {
     "test": "node scripts/run-tests.js",
     "pack:check": "node --test tests/package.test.js",
-    "release:identity": "node scripts/verify_release_identity.mjs"
+    "release:identity": "node scripts/verify_release_identity.mjs",
+    "docs:flow": "node scripts/generate-readme-flow.mjs"
   }
 }