@cassiomc1/forgeloop 0.1.11 → 0.1.12

package/PROTOCOL_INTEGRATION.md

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

@@ -8,13 +8,14 @@ accessibility, design, and web games across web, mobile, and desktop projects.
 
 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
+`.github/copilot-instructions.md`. The integration contract and capability levels are documented
+in [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md). Adopt only the guides
 relevant to the target project.
 
-ForgeLoop is the portable, evidence-first loop that connects deterministic
-routing, checkpointed state, observable evidence, conformance, and delegation
-for compatible agent harnesses.
+ForgeLoop is a portable, verifiable engineering protocol for AI coding environments
+and developer workflows. It turns intent into contract-driven execution with
+deterministic routing, resumable state, evidence-backed verification, recovery, and
+validator-backed completion.
 
 The npm package also ships the local `forgeloop` CLI. In a target project it
 installs canonical documents under `.forgeloop/kit/`, keeps only small native
@@ -54,141 +55,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 +88,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. Thin
+native adapters support common discovery surfaces including Codex, Claude Code,
+Cursor, and GitHub Copilot, while Antigravity, OpenCode, Hermes, Pi, Command Code,
+Freebuff, custom agents, and developer workflows discover the shared `AGENTS.md`
+entry point or manual bootstrap. All environments delegate to the same canonical
+protocol; see [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) for
+capability levels, degradation rules, and precedence notes.
 
 ### Migration recovery and release freeze
 
@@ -249,6 +124,87 @@ requirement-specific terminal result recording, legal repeated verification
 cycles, future-result and compound-evidence safeguards, and lifecycle-ledger
 divergence detection.
 
+## 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
 
 The npm CLI targets Node.js 20 or newer and installs the kit into an existing
@@ -371,7 +327,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 +482,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 +534,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.
 
@@ -667,7 +624,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,9 @@ 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` |
 
 ## 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.12",
+  "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"
   }
 }

package/src/core/discovery-surfaces.js

@@ -0,0 +1,22 @@
+export const DISCOVERY_SURFACES = Object.freeze([
+  Object.freeze({
+    id: "agents-md",
+    path: "AGENTS.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "claude-md",
+    path: "CLAUDE.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "cursor-rule",
+    path: ".cursor/rules/project-loop.mdc",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "github-repository-instructions",
+    path: ".github/copilot-instructions.md",
+    kind: "project-instructions",
+  }),
+]);

package/src/core/inspect.js

@@ -1,5 +1,5 @@
 import { fileExists, ensureWithin, readBytes } from "./filesystem.js";
-import { AGENT_SUPPORT } from "./agent-support.js";
+import { DISCOVERY_SURFACES } from "./discovery-surfaces.js";
 import { readManifest } from "./manifest.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { inspectSchemaHealth } from "./schema-validation.js";
@@ -42,15 +42,14 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     ? `${FORGELOOP_KIT_DIR}/schemas`
     : "schemas";
   const doctor = await runDoctor({ target, packageRoot });
-  const agents = await Promise.all(AGENT_SUPPORT.map(async (record) => ({
-    id: record.id,
-    name: record.name,
-    support: record.support,
-    instructionFiles: record.instructionFiles,
-    available: (await Promise.all(
-      record.instructionFiles.map(async (relativePath) => fileExists(ensureWithin(target, relativePath))),
-    )).some(Boolean),
+  const surfaces = await Promise.all(DISCOVERY_SURFACES.map(async (surface) => ({
+    id: surface.id,
+    path: surface.path,
+    kind: surface.kind,
+    available: await fileExists(ensureWithin(target, surface.path)),
   })));
+  const availableSurfaces = surfaces.filter((surface) => surface.available);
+  const protocolActivated = availableSurfaces.length > 0;
 
   const findings = [...doctor.findings];
   for (const schema of schemaHealth.schemas) {
@@ -100,9 +99,20 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
       error: manifestError,
     },
     profile,
+    integration: {
+      protocolActivated,
+      protocolMarker: "FORGELOOP_PROJECT_PROTOCOL=REQUIRED",
+      discovery: {
+        status: protocolActivated ? "INSTRUCTION_DISCOVERED" : "INSTRUCTION_ABSENT",
+        surfaces,
+      },
+      capability: {
+        status: "NOT_VERIFIED",
+      },
+    },
     adapters: {
-      detected: agents.filter((agent) => agent.available).map((agent) => agent.id),
-      agents,
+      detected: availableSurfaces.map((s) => s.path),
+      surfaces,
     },
     protocol: {
       version: PROTOCOL_VERSION,
@@ -112,7 +122,8 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     },
     state: { ...state, path: WORK_STATE_PATH, present: statePresent },
     compatibility: {
-      agents: AGENT_SUPPORT.map((record) => record.id),
+      deprecated: true,
+      agents: [],
     },
     findings,
     evidence,