@cassiomc1/forgeloop 0.1.10 → 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,83 +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
-  root["FORGELOOP"]
-
-  root --> entry["native adapters<br/>+ .forgeloop/kit/"]
-  entry --> migration{"target<br/>layout"}
-  migration -->|legacy v1| plan["validate paths<br/>+ build plan"]
-  plan --> hidden["write hidden<br/>kit"]
-  hidden --> verified["verify hidden<br/>bytes"]
-  verified --> authority["atomic manifest<br/>authority switch"]
-  authority --> cleanup["hash-checked<br/>legacy cleanup"]
-  cleanup --> recovered["healthy or<br/>recoverable"]
-  hidden -. interruption .-> incomplete["doctor: E_MIGRATION_INCOMPLETE"]
-  verified -. interruption .-> incomplete
-  authority -. interruption .-> incomplete
-  cleanup -. interruption .-> incomplete
-  migration -->|layout v2| retry["update + retry<br/>owned cleanup"]
-  incomplete --> retry
-  entry --> discovery["discovery +<br/>project profile"]
-  discovery --> contract["current<br/>contract"]
-  contract --> routing["deterministic<br/>route"]
-
-  contract --> preflight["preflight"]
-  routing --> preflight
-  gates["required<br/>gates"] --> preflight
-  preflight -->|READY| ready["PREFLIGHT_READY"]
-  preflight -->|BLOCKED| blocker["repair /<br/>blocker"]
-
-  ready --> state["work-state<br/>checkpoint"]
-  ready --> events["append-only<br/>event ledger"]
-  state --> lifecycle["plan → execute<br/>→ verify → review"]
-  lifecycle --> prepare["prepare<br/>completion receipt"]
-  prepare --> checks["checks + structured<br/>evidence"]
-  checks --> receipt["updated execution<br/>receipt"]
-  checks --> audit["audit +<br/>complete"]
-  events --> audit
-
-  contract --> freshness["freshness<br/>fingerprints"]
-  routing --> freshness
-  state --> freshness
-  checks --> freshness
-  routing --> conformance["validate-protocol<br/>/ conformance"]
-  state --> conformance
-  receipt --> conformance
-  freshness --> conformance
-  conformance --> verdict["VALID / INCOMPLETE /<br/>STALE / INCONSISTENT / INVALID"]
-  audit --> verdict
-
-  routing --> delegation["optional bundle /<br/>delegation"]
-  checks --> delegation
-  delegation --> handoff["handoff to<br/>compatible harness"]
-  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 state;
-  class checks,receipt,audit evidence;
-  class contract,freshness,conformance fact;
-  class gates,blocker gate;
-  class verdict result;
-  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
@@ -141,22 +72,29 @@ cleanup is diagnosed by `doctor` as `E_MIGRATION_INCOMPLETE` and retried by
 discovery creates the contract and deterministic route; contract, route, and
 required gates must produce `PREFLIGHT_READY` before the resumable state and
 append-only event ledger authorize the lifecycle. Verification produces
-structured evidence and a receipt. `audit`/`complete` and `validate-protocol`
-then classify the result as `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or
+structured evidence evaluated by one canonical readiness model. Failed checks
+enter diagnosis and correction. An evidence-only completion rejection records
+`COMPLETION_REJECTED` and opens a new numbered verification cycle without
+editing protocol JSON manually. `audit`, `complete`, and `validate-protocol`
+classify the result as `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or
 `INVALID`. Optional delegation creates a handoff; it is not an agent runtime.
 
 The operational request loop remains:
 
 ```text
 Request → discovery → profile → routing → plan → execution
-        → verification → correction when needed → final evidence
+        → verification → review → completion validation
+              ↑             │
+              └ 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
 
@@ -179,15 +117,93 @@ 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
-tests locally; CI does not download npm packages.
+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.
+
+## 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
+```
 
-The current published baseline for a reproducible blind run is
-`@cassiomc1/forgeloop@0.1.9`. The supplied hardening brief's `0.1.8` reference
-is historical; never move `v0.1.8` or `v0.1.9`, and use the read-only release
-identity verifier before a live run. The repository candidate is `0.1.10`, but
-it is not published: its completion-validation and cleanup TOCTOU fixes are not
-part of the frozen `0.1.9` tarball. Publish, tag, and repeat identity
-verification before a blind run that needs those executable changes.
+ForgeLoop should determine how to execute and verify the work.
 
 ### Use with npm
 
@@ -196,12 +212,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.9`.
+The current published release is `@cassiomc1/forgeloop@0.1.11`.
 Pin this version when a reproducible blind run or release-identity check is
 required:
 
 ```bash
-npx @cassiomc1/forgeloop@0.1.9 --version
+npx @cassiomc1/forgeloop@0.1.11 --version
 npx @cassiomc1/forgeloop init
 npx @cassiomc1/forgeloop doctor
 npx @cassiomc1/forgeloop update
@@ -225,6 +241,7 @@ npx @cassiomc1/forgeloop advance --to EXECUTING
 npx @cassiomc1/forgeloop advance --to VERIFYING
 npx @cassiomc1/forgeloop prepare-completion --json
 npx @cassiomc1/forgeloop record-check --id tests --requirement tests --status passed --evidence-kind OBSERVED --command "npm test" --result "exit 0" --exit-code 0 --json
+npx @cassiomc1/forgeloop record-terminal-result --requirement "Package published" --type PUBLICATION --status published --source "npm publish" --result "Published package to npm" --json
 npx @cassiomc1/forgeloop advance --to REVIEWING
 npx @cassiomc1/forgeloop audit --json
 npx @cassiomc1/forgeloop complete --json
@@ -257,6 +274,7 @@ implementation
 → forgeloop next
 → advance --to REVIEWING
 → forgeloop next
+→ (record-terminal-result if publication/production required)
 → complete
 ```
 
@@ -309,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
@@ -464,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
@@ -515,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.
 
@@ -605,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

@@ -17,6 +17,7 @@ remaining trust boundaries and their executable evidence.
 | Malicious work-state | Resumes stale, secret-bearing, or invalid work | `.forgeloop/work-state.json` | Schema/semantic checks, version checks, transition checks, contract/HEAD/artifact freshness, secret scan, size/depth bounds | Freshness cannot prove that an external process did not alter a file immediately afterward | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, `tests/security-limits.test.js` |
 | Forged preparation | Makes an agent's prose claim look like a completed preflight | Contract, route, gate, and preflight artifacts | Canonical SHA-256 fingerprints, guide-declared gate requirements, stale-artifact checks, and `E_*` failures | The CLI cannot stop a separate process from writing project files before preflight | `tests/protocol-artifacts.test.js`, `tests/preflight.test.js` |
 | Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |
+| Lifecycle artifact repair | Direct state or receipt edits fabricate a legal recovery or terminal phase | Work state, receipt, evidence checks, and event ledger | New verification cycles record phase events and fingerprints; validators reject state/ledger divergence and future lifecycle evidence | Local artifacts are detection-oriented, not cryptographically tamper-proof against a privileged process rewriting every linked artifact | `tests/lifecycle-evidence-recovery.test.js`, `tests/completion-ergonomics.test.js` |
 | Unsupported profile fact | Turns an agent decision into a durable user fact | `PROJECT_PROFILE.md` and `.forgeloop/sources.json` | Source IDs, source-kind validation, unknown-reference rejection, and explicit misclassification failures | Arbitrary Markdown semantics still require a human or host-specific parser | `tests/profile-provenance.test.js`, `src/core/profile.js` |
 | Weak verification | Treats a vague or inferred claim as observed evidence | Receipt checks and coverage | Versioned check schema, contradictory-status rejection, observed-evidence requirements, and coverage matrix | Evidence remains local and declarative; it is not a remote attestation service | `tests/evidence-coverage.test.js`, `tests/completion.test.js` |
 | Malicious receipt | Turns local claims into false publication or completion claims | Execution receipt JSON | Semantic evidence checks for completion, checks, review, push, commit, and deployment; explicit publication booleans | Evidence text is declarative and must still be reviewed for provenance | `tests/receipt-semantics.test.js`, `tests/observability.test.js` |
@@ -29,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.10",
-  "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/schemas/current-contract.schema.json

@@ -17,6 +17,36 @@
     "unresolvedDecisions",
     "sourceRefs"
   ],
+  "$defs": {
+    "requirement": {
+      "type": "object",
+      "required": ["text"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "text": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["PRODUCT", "VERIFICATION", "LIFECYCLE", "PUBLICATION", "PRODUCTION_READINESS"] },
+        "operator": { "enum": ["SINGLE", "ALL"] },
+        "requiredEvidenceKind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED", "HYPOTHESIS"] },
+        "lifecycleOwned": { "type": "boolean" },
+        "terminalOwned": { "type": "boolean" },
+        "mixedTerminal": { "type": "boolean" },
+        "requiredPublicationStatus": {
+          "type": "string",
+          "enum": ["committed", "pushed", "published", "deployed"]
+        },
+        "requirements": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/$defs/requirement" }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
   "properties": {
     "schemaVersion": { "const": 1 },
     "protocolVersion": { "const": 1 },
@@ -40,8 +70,24 @@
     "deliverables": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "constraints": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "risks": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "verification": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "successCriteria": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "verification": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string", "minLength": 1 },
+          { "$ref": "#/$defs/requirement" }
+        ]
+      }
+    },
+    "successCriteria": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string", "minLength": 1 },
+          { "$ref": "#/$defs/requirement" }
+        ]
+      }
+    },
     "stopConditions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "unresolvedDecisions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "sourceRefs": { "type": "array", "items": { "type": "string", "minLength": 1 } }

package/schemas/evidence.schema.json

@@ -9,6 +9,7 @@
     "kind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
     "source": { "type": "string", "minLength": 1 },
     "result": { "type": "string", "minLength": 1 },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
     "details": { "type": "object" }
   },
   "additionalProperties": false

package/schemas/execution-receipt.schema.json

@@ -11,6 +11,7 @@
     "contractFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "routeFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "stateFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
     "status": { "enum": ["in-progress", "complete", "blocked", "complete-with-concerns"] },
     "taskStatus": { "enum": ["in-progress", "complete", "blocked", "incomplete"] },
     "verificationStatus": { "enum": ["valid", "invalid", "not-verified", "blocked"] },
@@ -29,6 +30,7 @@
           "kind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
           "source": { "type": "string", "minLength": 1 },
           "result": { "type": "string", "minLength": 1 },
+          "verificationCycle": { "type": "integer", "minimum": 1 },
           "details": { "type": "object" }
         },
         "additionalProperties": false