@cassiomc1/forgeloop 0.1.11 → 0.1.13

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

@@ -3,30 +3,28 @@ description: Universal verified project loop
 alwaysApply: true
 ---
 
+<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
 # Cursor — Universal Project Loop
 
-1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) before planning or editing.
-2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize it in target projects when it remains in `template` mode.
-3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate all relevant guides and only those guides.
-4. Report the selected guide IDs.
-5. Respect higher-level and local instructions and the latest request.
-6. Make the minimum change, run a specific check, and then run proportional regression checks.
-7. Diagnose failures before fixing them and do not repeat an attempt without new evidence.
-8. Request authority for unrelated external or destructive actions, installations, and publications. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-9. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+This project is ForgeLoop-enabled. If your execution environment loaded this
+file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
+Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
 
-After implementation work for the current task is complete, run `forgeloop next`
-before returning a final result. Follow the returned lifecycle action until
-ForgeLoop reaches a terminal state or an explicit blocker.
+1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../../PROTOCOL_INTEGRATION.md).
+2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize if in `template` mode.
+3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate relevant guides and report IDs.
+4. Respect higher-level and local instructions and the latest request.
+5. Make the minimum change, run specific checks, and run proportional regression checks.
+6. Diagnose failures before fixing them; do not repeat attempts without new evidence.
+7. Request authority for unrelated actions, installations, and publications. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+8. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
-10. Report only demonstrated results and checks.
+After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 
-Do not stop for non-blocking missing product details. When a safe, reversible
-local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
-load-bearing, irreversible, externally consequential, unsafe, or real
-user/business decisions.
+9. Report only demonstrated results and checks.
 
-The loop and router are canonical sources; do not duplicate domain rules.
+Do not stop for non-blocking missing product details. When a safe, reversible
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 
 ## Pre-question decisions
 

package/.github/copilot-instructions.md

@@ -1,30 +1,27 @@
+<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
 # GitHub Copilot — Universal Project Loop
 
-Use these instructions across the repository while preserving more specific
-directory or file rules.
+This project is ForgeLoop-enabled. If your execution environment loaded this
+file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
+Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
 
-- Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) before implementing.
-- Confirm [`PROJECT_PROFILE.md`](../PROJECT_PROFILE.md) from evidence. Initialize it in a target project when it remains in `template` mode.
-- Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md); use all applicable guides and only those guides.
-- Report the activated guide IDs.
+Use these instructions across the repository while preserving local rules.
+
+- Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../PROTOCOL_INTEGRATION.md).
+- Confirm [`PROJECT_PROFILE.md`](../PROJECT_PROFILE.md) from evidence; initialize if in `template` mode.
+- Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) and report activated guide IDs.
 - Respect the latest request, scope, and higher-level instructions.
-- Make the smallest coherent change and validate it with a specific check followed by proportional regression checks.
-- Diagnose the cause before fixing a failure; do not make random attempts.
-- Do not install unrelated software, publish, delete, migrate, or alter external state without authority. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-- After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+- Make the smallest coherent change; validate with specific and regression checks.
+- Diagnose causes before fixing failures; do not make unverified attempts.
+- Do not install software, publish, delete, or alter external state without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+- After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
 
-After implementation work for the current task is complete, run `forgeloop next`
-before returning a final result. Follow the returned lifecycle action until
-ForgeLoop reaches a terminal state or an explicit blocker.
+After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
 
-- Report the result, checks actually run, limitations, and publication state.
+- Report results, checks actually run, limitations, and publication state.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
-local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
-load-bearing, irreversible, externally consequential, unsafe, or real
-user/business decisions.
-
-The loop and router are canonical; do not replicate domain rules here.
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 
 ## Pre-question decisions
 

package/AGENTS.md

@@ -1,31 +1,25 @@
+<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
 # Universal Project Loop Instructions
 
-These instructions apply to the entire repository unless a closer, more
-specific rule overrides them.
-
-1. Follow platform rules, the user's latest request, and applicable local instructions first.
-2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) before planning or changing files.
-3. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from their sources; initialize the profile in a target project when it is still in `template` mode.
-4. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select all relevant guides and only those guides.
-5. Briefly report the activated guide IDs.
-6. Make the smallest coherent change, run specific checks, and then run proportional regression checks.
-7. Diagnose a failure before fixing it; do not repeat the same attempt without new evidence.
-8. Do not install unrelated software, publish, delete, migrate data, or change external systems without applicable authority. For a task-scoped missing Qwen-MM-Plugins capability, follow the discovery protocol in `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-9. Before implementation, create/validate `.forgeloop/current-contract.json`, persist deterministic routing, satisfy mandatory gates, and require `forgeloop preflight` to return `READY`.
-10. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
-11. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING`, record structured evidence, reach `REVIEWING`, prepare/update the execution receipt, and require `forgeloop complete` to return `VALID`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
-
-12. After implementation work for the current task is complete, run `forgeloop next`
-before returning a final result. Follow the returned lifecycle action until
-ForgeLoop reaches a terminal state or an explicit blocker.
-13. Finish with the result, checks actually run, limitations, and publication state.
+This project is ForgeLoop-enabled. If your execution environment loaded this
+file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
+Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
+
+1. Follow platform rules, the user's latest request, and local instructions first.
+1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
+1. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from sources; initialize if in `template` mode.
+1. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select relevant guides and report activated guide IDs.
+1. Make the smallest coherent change, run specific checks, and proportional regression checks.
+1. Diagnose failures before fixing; do not repeat attempts without new evidence.
+1. Do not install software, publish, delete, or migrate data without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+1. Before implementation, create/validate `.forgeloop/current-contract.json`, persist routing, satisfy gates, and require `forgeloop preflight` to return `READY`.
+1. Before claiming `COMPLETE`, require `forgeloop complete` to return `VALID`; otherwise report completion as not protocol-verified.
+1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
+1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
+1. Finish with result, checks run, limitations, and publication state.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
-local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
-load-bearing, irreversible, externally consequential, unsafe, or real
-user/business decisions.
-
-The guides provide technical defaults; explicit requirements and project evidence prevail.
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 
 ## Pre-question decisions
 

package/AGENT_COMPATIBILITY.md

@@ -1,214 +1,7 @@
-# Agent Compatibility
+# Deprecated filename
 
-`@cassiomc1/forgeloop` installs one canonical engineering loop and the smallest
-native entry point required by each supported agent. The package does not
-install an agent, configure a provider, or run a live model session.
+ForgeLoop is vendor-neutral and does not use a supported-agent allowlist.
 
-Compatibility has three distinct levels:
+The canonical integration contract is:
 
-- `ADAPTER_COMPATIBLE`: the harness recognizes the installed instruction entry
-  file.
-- `PROTOCOL_CAPABLE`: the harness can create the local contract, route, gates,
-  state, evidence, and receipt artifacts and run the validators.
-- `CONFORMANCE_VERIFIED`: a live run passed one of the scenarios under
-  `conformance/` for that harness/model combination.
-
-Reading `AGENTS.md` proves only instruction compatibility. It does not prove
-that an active session followed preflight, legal phase chronology, or completion
-validation.
-
-## Optional capability extensions
-
-The installed loop can direct the active agent to inspect its native model and
-harness capabilities. When a task requires a missing multimodal capability,
-the agent may install the smallest task-scoped `Qwen-MM-Plugins` capability
-through the harness's native mechanism or the official upstream installer,
-then verify that the skill/MCP tool is callable before using it. This does not
-turn the package into a model runtime or provider configuration tool: API keys,
-system dependencies, and unrelated environment changes remain separately
-gated. Live model sessions and external plugin installation are outside the
-reproducible `npm test` boundary.
-
-## Support matrix
-
-| Agent | Support | Reads in the installed project | Official documentation |
-| --- | --- | --- | --- |
-| Codex | Direct adapter | `AGENTS.md` | [OpenAI — Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) |
-| Claude Code | Direct adapter | `CLAUDE.md` | [Anthropic — How Claude remembers your project](https://code.claude.com/docs/en/memory) |
-| Cursor | Direct adapter | `AGENTS.md`, `.cursor/rules/project-loop.mdc` | [Cursor — Rules](https://cursor.com/docs/rules) |
-| GitHub Copilot | Direct adapter | `.github/copilot-instructions.md` | [GitHub — Repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions-in-your-ide/add-repository-instructions-in-your-ide) |
-| Antigravity | `AGENTS.md` compatibility | `AGENTS.md` | [Antigravity — CLI best practices](https://antigravity.google/docs/cli/best-practices) |
-| OpenCode | `AGENTS.md` compatibility | `AGENTS.md` | [OpenCode — Rules](https://opencode.ai/docs/rules/) |
-| Hermes | `AGENTS.md` compatibility | `AGENTS.md` | [Hermes — Context files](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/context-files.md) |
-| Pi | `AGENTS.md` compatibility | `AGENTS.md` | [Pi — Coding-agent SDK and context files](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/sdk.md) |
-| Command Code | `AGENTS.md` compatibility | `AGENTS.md` | [Command Code — Memory](https://commandcode.ai/docs/core-concepts/memory) |
-| Freebuff | `AGENTS.md` compatibility | `AGENTS.md` | [Freebuff — Knowledge file names](https://github.com/CodebuffAI/freebuff/blob/main/common/src/constants/knowledge.ts) |
-
-## What direct and compatibility mean
-
-Direct adapters are files with a format or location specifically documented
-by the agent. Compatibility entries use the same root `AGENTS.md`; no second
-copy of the loop is needed because the agent officially recognizes that file.
-
-Claude Code is the important exception: it reads `CLAUDE.md`, not `AGENTS.md`.
-The package therefore installs both files, with the Claude-specific adapter
-pointing to the same canonical loop documents.
-
-Codex, Cursor, and GitHub Copilot may also discover `AGENTS.md` on some
-surfaces. The dedicated files remain useful because they make the behavior
-explicit and cover each product's native entry point.
-
-## Harness capability and bootstrap boundary
-
-An adapter proves that the package installed a supported instruction or context
-entry point. It is not proof of a callable optional tool, isolation feature,
-review primitive, or bootstrap hook in the active harness, even when the
-canonical loop can use one when available.
-
-When a harness supports native context bootstrap or startup verification, prefer
-an explicit unique marker to confirm that the expected instruction path is
-active. When that proof is unavailable, treat the adapter file and repository
-checks as installation evidence only.
-
-Optional capability gaps use the loop fallback rules instead of invented
-commands or assumed integrations. Agents should never invent a tool call to
-simulate missing harness support. Global configuration, provider credentials,
-system packages, and other machine-level setup remain outside the installed
-package boundary.
-
-## Precedence and existing instructions
-
-`forgeloop init` never overwrites an existing instruction file. If the target
-already contains a more specific or higher-priority file, that agent may use
-it instead of the installed entry point:
-
-- Codex can use `AGENTS.override.md` before `AGENTS.md`.
-- Claude Code combines `CLAUDE.md` and closer `CLAUDE.local.md` files.
-- Cursor may combine project rules with user rules and nested rules.
-- Antigravity can add workspace rules under `.agents/rules/`.
-- Hermes gives `.hermes.md`/`HERMES.md` priority over `AGENTS.md`.
-- OpenCode can add instructions through `opencode.json` and uses
-  `CLAUDE.md` as a fallback when `AGENTS.md` is absent.
-- Freebuff recognizes `knowledge.md`, `AGENTS.md`, and `CLAUDE.md`; an existing
-  higher-priority knowledge file can affect which project context is loaded.
-
-When a target already has local rules, keep them and merge only the relevant
-loop reference manually. Run `doctor --path /path/to/project` after resolving
-the merge so missing files and managed drift are visible.
-
-## External workflow compatibility
-
-An external planning, brainstorming, design-review, testing, or documentation
-workflow can be installed and still be `INCOMPATIBLE WITH AUTONOMOUS MODE`.
-Installation is a capability fact; compatibility is a precedence and behavior
-fact. The ForgeLoop `NON_BLOCKING` classification remains authoritative in
-autonomous mode. A mandatory approval policy for a reversible local choice is
-recorded as `WORKFLOW_CONFLICT`, with no user question and no fake entry in
-`current-contract.unresolvedDecisions[]`.
-
-The supported autonomous boundary is:
-
-| Workflow policy | Result |
-| --- | --- |
-| Local planning, review, tests, or docs | Compatible. |
-| Approval only for a real ForgeLoop `BLOCKING` decision | Compatible; the justified question may proceed. |
-| Approval for every design choice or before implementation | `INCOMPATIBLE WITH AUTONOMOUS MODE`. |
-| Reclassifying reversible aesthetics as blocking | `INCOMPATIBLE WITH AUTONOMOUS MODE`. |
-
-Interactive operation is explicit (`autonomousMode=false`) and must not be
-selected silently. Live conformance records the available and invoked external
-workflows, mandatory-approval setting, brainstorming/design hard gates,
-autonomy mode, process count, subagent count, and delegation status. For the
-sixth blind run, the harness must report:
-
-```text
-mandatory-approval workflows enabled: NO
-external brainstorming hard gate enabled: NO
-external design approval gate enabled: NO
-subagents enabled: NO
-delegation enabled: NO
-```
-
-Question attribution remains `USER_REQUIREMENT`,
-`FORGELOOP_BLOCKING_DECISION`, `EXTERNAL_WORKFLOW_POLICY`, or
-`MODEL_PREFERENCE`. In autonomous mode, only the first two can authorize a
-question, and `ASK_USER` additionally requires a valid ForgeLoop blocking
-reason. External policy alone cannot manufacture a blocker.
-
-If a mandatory approval workflow cannot be disabled, the run is
-`TEST_NOT_STARTED`; do not call it a failed or successful conformance result.
-
-## Deterministic verification boundary
-
-The repository verifies package contents, adapter paths, installation into a
-selected target directory, and the official instruction-file contracts. It
-does not launch Codex, Claude Code, or another provider during `npm test`; live
-sessions require external authentication and are intentionally outside the
-reproducible package test suite.
-
-## Protocol-support commands and degraded mode
-
-The CLI can deterministically evaluate declared routing signals, inspect target
-health, validate local receipts and work state, and report resumable status. It
-does not call an LLM, schedule agents, execute commands from
-`PROJECT_PROFILE.md`, or provide `forgeloop run`/orchestration commands.
-
-If a harness has no subagents, worktrees, web access, MCP, persistent state, or
-Git checkout, the compatible agent continues inline and reports the missing
-capability as a limitation. Inline execution is not independent review, a
-non-Git target cannot provide branch/HEAD drift evidence, and a missing remote
-service is a blocker rather than a simulated success.
-
-The degraded-mode contract is explicit:
-
-| Missing capability | Required behavior |
-| --- | --- |
-| Subagents | Execute the same brief inline; do not claim delegation or independent review. |
-| Worktrees or isolation | Keep ownership boundaries in the brief and serialize conflicting work. |
-| Web or MCP | Use a local equivalent only when it provides compatible evidence; otherwise mark the check not verified or blocked. |
-| Persistent state | Keep the handoff in the current session and report that resume across sessions is unavailable. |
-| Git checkout | Continue with local file evidence, but report that branch/HEAD drift cannot be verified. |
-
-These are limitations of the active harness, not reasons to invent a command,
-provider, remote service, or successful check.
-
-## Installed files
-
-Every initialized project receives small native adapters at the project root
-and the canonical documents in the package-managed hidden kit. This keeps the
-root readable while preserving the standard instruction entry points:
-
-```text
-AGENTS.md
-CLAUDE.md
-.cursor/rules/project-loop.mdc
-.github/copilot-instructions.md
-.forgeloop/manifest.json
-.forgeloop/current-contract.json
-.forgeloop/routing-result.json
-.forgeloop/work-state.json
-.forgeloop/kit/AGENT_COMPATIBILITY.md
-.forgeloop/kit/LOOP_ENGINEERING.md
-.forgeloop/kit/GUIDE_ROUTER.md
-.forgeloop/kit/PROJECT_PROFILE.md
-.forgeloop/kit/LOOP_SYSTEM_DESIGN.md
-.forgeloop/kit/QUALITY_SCORECARD.md
-.forgeloop/kit/TERMINOLOGY.md
-.forgeloop/kit/EXECUTION_STATE.md
-.forgeloop/kit/DELEGATION_PROTOCOL.md
-.forgeloop/kit/ORCHESTRATOR_INTEGRATION.md
-.forgeloop/kit/THIRD_PARTY_NOTICES.md
-.forgeloop/kit/LICENSE
-.forgeloop/kit/LICENSE-DOCS.md
-.forgeloop/kit/ENG/
-.forgeloop/kit/schemas/
-```
-
-The package source retains the canonical root files so npm can ship and
-validate them; initialized targets use the hidden destination above. Existing
-legacy root files are not deleted when they are modified or unowned. Run
-`forgeloop update` to migrate unchanged managed files and review any reported
-conflict.
-
-See the main [README](https://github.com/cassiomc1/forgeloop#readme) for the complete `npx` installation,
-diagnostic, first-run, and update workflow.
+[`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)

package/CLAUDE.md

@@ -1,27 +1,25 @@
+<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
 # Claude Code — Universal Project Loop
 
-When working in this repository:
+This project is ForgeLoop-enabled. If your execution environment loaded this
+file, ForgeLoop applies regardless of model, provider, IDE, agent, or runtime.
+Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spirit".
 
-1. Follow higher-level instructions, the user's latest request, and the closest rules for the file in scope.
-2. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) before planning or editing.
-3. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources. Initialize it in a target project when it remains in `template` mode.
-4. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select all relevant guides and only those guides, and announce their IDs.
-5. Make small changes, run a specific check, and then run proportional regression checks.
-6. Investigate the root cause of a failure before fixing it.
-7. Request authority for unrelated installation, publication, deletion, migration, or another external or destructive action. For a task-scoped missing Qwen-MM-Plugins capability, follow `LOOP_ENGINEERING.md`; API credentials and system dependencies remain separately gated.
-8. After implementation begins, do not return a final result in `EXECUTING`: follow `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`; otherwise report `BLOCKED` or `PARTIALLY VERIFIED` with exact findings.
+When working in this repository:
 
-9. After implementation work for the current task is complete, run `forgeloop next`
-before returning a final result. Follow the returned lifecycle action until
-ForgeLoop reaches a terminal state or an explicit blocker.
-10. Report current evidence, limitations, and publication state without claiming checks that were not run.
+1. Follow higher-level instructions, the user's latest request, and local rules first.
+1. Read [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md).
+1. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources; initialize if in `template` mode.
+1. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select relevant guides, and announce their IDs.
+1. Make small changes, run specific checks, and run proportional regression checks.
+1. Investigate root causes before fixing failures; do not make unverified attempts.
+1. Request authority for unrelated installations, publications, deletions, or migrations. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.
+1. After implementation begins, do not return a final result in `EXECUTING`: advance through `VERIFYING` → structured evidence → `REVIEWING` → execution receipt → validator-backed `COMPLETE`. If closure cannot be reached, report `BLOCKED` or `PARTIALLY VERIFIED`.
+1. After implementation work for the current task is complete, run `forgeloop next` before returning a final result. Follow the returned lifecycle action until ForgeLoop reaches a terminal state or an explicit blocker.
+1. Report current evidence, limitations, and publication state without claiming checks that were not run.
 
 Do not stop for non-blocking missing product details. When a safe, reversible
-local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`. Ask only for
-load-bearing, irreversible, externally consequential, unsafe, or real
-user/business decisions.
-
-Do not duplicate guide rules here; treat the loop and router as canonical sources.
+local default exists, record it as an agent assumption and follow the Blocking vs Non-Blocking Decisions policy in `LOOP_ENGINEERING.md`.
 
 ## Pre-question decisions
 

package/LOOP_ENGINEERING.md

@@ -4,6 +4,110 @@
 > technical rules remain in the guides selected through
 > [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md).
 
+## Protocol applicability
+
+ForgeLoop is a project-local engineering protocol.
+
+If the active execution environment discovers a ForgeLoop project adapter,
+ForgeLoop applies to work performed in that project regardless of the
+environment's model, provider, product, IDE, agent name, runtime name, or
+orchestration implementation.
+
+Named integrations, documented discovery surfaces, previous conformance runs,
+and certification records are informational evidence only. They are never an
+allowlist.
+
+An execution environment that has not been previously tested is
+`CONFORMANCE_UNVERIFIED`, not `PROTOCOL_OPTIONAL`.
+
+```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."
+```
+
+### Unknown execution environment policy
+
+An unknown or undocumented execution environment is not a blocker by itself.
+
+If it discovered the ForgeLoop project adapter, evaluate capabilities:
+
+- If protocol-capable: execute ForgeLoop normally.
+- If capability-limited: execute all supported ForgeLoop dimensions, fail closed
+  for unavailable dimensions, and report limitations precisely.
+
+Never downgrade ForgeLoop to optional guidance solely because the runtime
+name is unknown.
+
+### CLI-owned artifact policy
+
+Lifecycle-owned ForgeLoop artifacts must be created or mutated only through
+the supported ForgeLoop lifecycle commands or canonical ForgeLoop APIs:
+
+- `.forgeloop/preflight.json`
+- `.forgeloop/work-state.json`
+- `.forgeloop/events.ndjson`
+- `.forgeloop/execution-receipt.json`
+- completion recovery metadata
+- canonical check/evidence state
+- terminal-result lifecycle state
+
+If the required CLI/API capability cannot be resolved:
+
+- do not fabricate current lifecycle state;
+- do not synthesize event history;
+- do not manually assign `COMPLETE`;
+- do not construct a fake execution receipt;
+- do not invent `record-check` evidence;
+- do not rewrite `events.ndjson` to simulate chronology.
+
+Report the corresponding ForgeLoop dimension as `NOT_VERIFIED` with
+`E_FORGELOOP_CLI_UNAVAILABLE`.
+
+### Missing verification tool policy
+
+A missing verification tool does not grant authority to install it.
+
+When a verification command or checker is unavailable:
+
+1. Try only already-installed or explicitly non-installing resolution paths.
+2. Prefer an already available equivalent when it can verify the same requirement.
+3. If no suitable local capability exists, request explicit installation authority
+   only when the missing verification is genuinely required.
+4. If authority is unavailable or the check is non-critical, record the affected
+   verification dimension as `NOT_VERIFIED` with `E_VERIFICATION_TOOL_UNAVAILABLE`.
+
+Do not retry a failed non-installing lookup with a command that implicitly
+downloads or installs the missing package.
+
+Examples of forbidden escalation without authority:
+
+```text
+npx --no-install TOOL → missing
+npx TOOL              → implicit install
+```
+
+```text
+command -v TOOL → missing
+package-manager install TOOL
+```
+
+```text
+local executable missing
+curl | sh
+```
+
+Automatic installation is allowed only when an explicit ForgeLoop rule grants
+that exact task-scoped installation authority and higher-priority platform/user
+rules permit it.
+
+A missing checker must never be converted into environmental mutation merely
+to make verification pass.
+
 ## Blocking vs Non-Blocking Decisions
 
 Classify every unresolved decision before deciding whether to ask the user.

package/LOOP_SYSTEM_DESIGN.md

@@ -10,11 +10,13 @@ The system should use every guide that materially helps the task without loading
 
 ## Primary decisions
 
-- The package supports Codex, Claude Code, Cursor, GitHub Copilot, Antigravity,
-  OpenCode, Hermes, Pi, Command Code, and Freebuff.
-- Codex, Claude Code, Cursor, and GitHub Copilot use native entry files; the
-  other six agents consume the shared `AGENTS.md` entry point.
-- The portable instruction layer uses Markdown and each agent's native instruction mechanism; the optional local Node CLI validates and installs the kit without an agent runtime or third-party dependency.
+- The protocol is vendor-neutral, project-scoped, and capability-based,
+  supporting any AI agent, coding assistant, IDE runtime, or developer workflow.
+- Common discovery surfaces (e.g. `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`,
+  `.github/copilot-instructions.md`) use project-local shims delegating to the
+  canonical protocol under `.forgeloop/kit/`, while other environments use the
+  shared `AGENTS.md` entry point or manual bootstrap.
+- The portable instruction layer uses Markdown and each environment's native instruction mechanism; the optional local Node CLI validates and installs the kit without an agent runtime or third-party dependency.
 - English is the only language used by repository content and guide metadata.
 - The agent uses all applicable guides, not every file indiscriminately.
 - Design, planning, test-first, and review process gates live in the canonical loop and scale with task risk instead of becoming unconditional boilerplate in every adapter or architecture note.
@@ -131,11 +133,11 @@ GitHub Copilot adapter. It activates the same operational contract while preserv
 
 Always-applicable Cursor adapter. It delegates decisions to the loop and router.
 
-### `AGENT_COMPATIBILITY.md`
+### `PROTOCOL_INTEGRATION.md`
 
-Human-readable support matrix for all ten agents. It explains each native entry
-file, the shared `AGENTS.md` compatibility contract, official documentation,
-precedence caveats, and the deterministic verification boundary.
+Human-readable integration protocol and capability levels. It explains native entry
+points, discovery surfaces, required and optional capabilities, degradation,
+and the deterministic verification boundary.
 
 ### `LOOP_ENGINEERING.md`
 
@@ -389,8 +391,8 @@ update practice.
 ## Acceptance criteria
 
 - The repository and its maintained content are English-only.
-- All ten supported agents have a documented entry into one canonical loop,
-  with native adapters distinguished from shared `AGENTS.md` compatibility.
+- Common project instruction surfaces and generic bootstrap mechanisms have a
+  documented entry into one canonical loop.
 - The router selects every relevant guide and excludes irrelevant guides in the six defined scenarios.
 - The profile contains verifiable facts, sources, and real commands without secrets.
 - The loop requires evidence before completion claims and exits safely when blocked.