@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/.github/copilot-instructions.md

@@ -8,6 +8,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 Use these instructions across the repository while preserving local rules.
 
 - Read [`LOOP_ENGINEERING.md`](../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../PROTOCOL_INTEGRATION.md).
+- If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 - 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.

package/AGENTS.md

@@ -7,6 +7,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 
 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. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 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.

package/AGENT_COMPATIBILITY.md

@@ -1,5 +1,9 @@
 # Deprecated filename
 
+> Deprecated since package `1.2.4`; retained as a repository compatibility stub.
+> It is not part of the public integration surface and is scheduled for removal
+> in the next compatibility-breaking release.
+
 ForgeLoop is vendor-neutral and does not use a supported-agent allowlist.
 
 The canonical integration contract is:

package/CLAUDE.md

@@ -9,6 +9,7 @@ When working in this repository:
 
 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. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 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.

package/DOCS_INDEX.md

@@ -1,5 +1,12 @@
 # Documentation index
 
+The machine-readable inventory is
+[`docs/documentation-manifest.json`](./docs/documentation-manifest.json). It
+classifies every package-shipped document, names canonical concept owners, and
+records generated/deprecated-document metadata. Normative requirements and
+their implementation/test mappings are in
+[`docs/protocol-requirements.json`](./docs/protocol-requirements.json).
+
 ForgeLoop keeps one canonical process and separates protocol behavior from
 integration and guide context. Use this map before editing documentation.
 
@@ -13,7 +20,11 @@ integration and guide context. Use this map before editing documentation.
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
 | Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
 | Operational recipes | [`docs/RECIPES.md`](./docs/RECIPES.md) | Short copy-paste recipes for daily workflows |
+| Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
+| Local-first MCP adapter | [`docs/MCP.md`](./docs/MCP.md) | stdio default, optional strict loopback HTTP; server modes/capabilities and canonical resources |
 | Documentation guide | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) | Rules and checklist for modifying documentation |
+| ForgeLoop 1.5/MCP release checklist | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) | Integration API v1, MCP package, and publication gates |
+| ForgeLoop 1.4 release checklist | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) | Claim-recovery, compatibility, package, and publication gates |
 | Lifecycle, gates, planning, verification, and recovery | [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) | Normative process for agents and developer workflows |
 | Capability levels, discovery, and degradation | [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) | Vendor-neutral harness contract |
 | Host/orchestrator integration | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) | Serializable phases, transition boundaries, host responsibilities, and no-runtime integration contract |
@@ -39,6 +50,8 @@ integration and guide context. Use this map before editing documentation.
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
 | **Documentation contributor** | [`docs/DOCUMENTATION_GUIDE.md`](./docs/DOCUMENTATION_GUIDE.md) |
+| **Release maintainer (current)** | [`docs/RELEASE_CHECKLIST_1_5_MCP.md`](./docs/RELEASE_CHECKLIST_1_5_MCP.md) |
+| **Release maintainer (historical 1.4)** | [`docs/RELEASE_CHECKLIST_1_4.md`](./docs/RELEASE_CHECKLIST_1_4.md) |
 | **Protocol architect / maintainer** | [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) + [`schemas/`](./schemas/) |
 | **Security auditor** | [`THREAT_MODEL.md`](./THREAT_MODEL.md) |
 | **Engineering guide author** | [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) + [`ENG/`](./ENG/) |
@@ -50,6 +63,7 @@ integration and guide context. Use this map before editing documentation.
 - **Check CLI options and syntax**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
 - **Understand what `.forgeloop/` stores**: [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
 - **Fix a blocked, stale, or invalid state**: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
+- **Recover a stale task or reacquire released claims**: [`docs/RECIPES.md`](./docs/RECIPES.md#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
 - **Find operational copy-paste commands**: [`docs/RECIPES.md`](./docs/RECIPES.md)
 - **Read the normative protocol specification**: [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrate a new AI environment**: [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)

package/EXECUTION_STATE.md

@@ -10,6 +10,27 @@ Compatible agents may persist a handoff checkpoint at:
 .forgeloop/task-state/<taskKey>/work-state.json
 ```
 
+Claim-release recovery has a separate current-state artifact:
+
+```text
+.forgeloop/task-state/<taskKey>/recovery.json
+```
+
+`work-state.json` remains the lifecycle authority. `recovery.json` records a
+request to suspend ordinary mutation and release effective claims; it does not
+change the phase, refresh repository evidence, erase failures, or imply
+completion. Its `recoveryId`, event sequence, previous revision, released
+claims, repository fingerprint, classification, and authority kind are bound
+to the append-only recovery event. Claims are released only after the canonical
+resolver validates that complete relationship. An unresolved recovery event
+with a missing tombstone, or a tombstone without its matching event, is
+`INCONSISTENT`, retains historical claims, and disables mutation. The same
+fail-closed rule applies to completion: `phase: COMPLETE` alone never releases
+claims — the canonical completion ownership proof (validated ledger with the
+task-bound `COMPLETION_VALIDATED` event and coherent state) is required, and a
+forged or unproven COMPLETE state is `INCONSISTENT` with historical claims
+retained.
+
 The file is local, ignored by Git, schema-versioned, and never a replacement
 for the manifest or the target project profile (installed as
 `.forgeloop/kit/PROJECT_PROFILE.md`). It contains no secrets and is untrusted
@@ -51,6 +72,14 @@ and rename it into place. The host filesystem's rename guarantee is the
 atomicity boundary; no database or remote state is involved. A truncated,
 malformed, or secret-bearing file is invalid and is never resumed silently.
 
+Lifecycle mutations that change more than one artifact use a task transaction
+under `.forgeloop/.txn/<transactionId>/`. The transaction records every staged
+replacement and append. Ledger appends validate a bounded tail checkpoint and
+stage only the new NDJSON suffix; if publication is interrupted, recovery
+truncates that suffix to its recorded pre-append size. A stale checkpoint never
+authorizes a new sequence number: ForgeLoop rebuilds it from the ledger before
+continuing.
+
 Before resuming, compare:
 
 - the task contract fingerprint;
@@ -58,6 +87,25 @@ Before resuming, compare:
 - the protocol version;
 - required artifacts and assumptions recorded by the task.
 
+If validated recovery state is active, ordinary lifecycle mutation fails with
+`E_TASK_RECOVERED`. If recovery ownership is inconsistent, mutation fails with
+`E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`. Resume claim ownership explicitly:
+
+```bash
+forgeloop task-resume --task <id> --json
+```
+
+Optional repeatable `--claim <path>` arguments replace the historical claim set
+only after normal overlap and clean-checkout enforcement succeeds. Recovery
+state deletion, any descriptor update, and `TASK_RECOVERY_RESUMED` are staged
+transactionally. `TASK_RECOVERY_RESUMED` counts as meaningful activity. A
+missing artifact returns `E_TASK_NOT_RECOVERED` only when the ledger also proves
+there is no unresolved recovery; otherwise it is an ownership inconsistency.
+
+Never create, delete, or edit `recovery.json` manually. Never remove recovery
+state to resume a task. Never interpret `recovery.json` without validating its
+ledger binding.
+
 Any material difference produces `REVALIDATION_REQUIRED`. A non-Git target
 reports that branch/HEAD drift is not verifiable. Cheap checks may be rerun,
 but a completed destructive or publication action is never rerun automatically.

package/LOOP_ENGINEERING.md

@@ -1275,7 +1275,7 @@ to inspect first.
 `CONTINUITY_CONTEXT_IS_NOT_EVIDENCE`: continuity may guide inspection but can
 never satisfy verification coverage, publication, production readiness, or
 completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
-installation or external action. The receiving harness MUST reconcile
+installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
 ## Multi-task concurrent project state
@@ -1289,7 +1289,7 @@ corruption through three fundamental protocol mechanisms:
    `taskKey` derived as `SHA-256(taskId)` in 64 lowercase hexadecimal characters. All
    task-scoped artifacts (`task.json`, `contract.json`, `routing-result.json`,
    `preflight.json`, `work-state.json`, `events.ndjson`, `execution-receipt.json`,
-   `continuity.json`, gates, and execution records) are stored strictly under
+   `continuity.json`, `recovery.json`, gates, and execution records) are stored strictly under
    `.forgeloop/task-state/<taskKey>/`. Shared repository configuration and sources
    (`config.json`, `sources.json`) remain at `.forgeloop/`.
 
@@ -1304,16 +1304,65 @@ corruption through three fundamental protocol mechanisms:
      (`E_TASK_SCOPE_FROZEN`).
    - At verification and completion, Git modifications are validated to ensure no changes
      escaped the task's declared scope (`E_TASK_CHANGE_OUTSIDE_SCOPE`).
+   - `task.json` retains historical claims. Effective claims are empty only after
+     validator-backed `COMPLETE` or when the canonical claim-state resolver
+     validates `recovery.json` against the descriptor, work state, and complete
+     hash-chained recovery history. A tombstone alone never releases claims.
+   - Fake, missing, corrupt, deleted, or mismatched recovery evidence is
+     `INCONSISTENT`: every provable historical claim remains reserved,
+     `mutationAllowed=false`, and overlapping claim acquisition fails with
+     `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`.
+   - Recovery is not completion. `task-recover` accepts only deterministic
+     `STALE` or `ABANDONED` classifications, preserves work state, receipts,
+     failures, policy, continuity, and repository fingerprints, and suspends
+     ordinary task mutation with `E_TASK_RECOVERED`.
+   - Only `forgeloop task-resume --task <id>` may remove recovery state. It
+     first validates recovery ownership and lifecycle revision, safely settles
+     only an unchanged stale task lease, then reacquires the released (or
+     explicitly supplied) claims through the normal overlap and clean-checkout
+     checks under the project claims lock. A claim held by another task remains
+     unavailable. `TASK_RECOVERY_RESUMED` is meaningful activity.
 
 3. **Per-Task Exclusive Mutex Locking**:
    Mutating lifecycle commands (`advance`, `preflight`, `run-check`, `complete`, etc.)
-   acquire an exclusive filesystem lock at `.forgeloop/task-state/<taskKey>/.lock` using
+   acquire an exclusive filesystem lock at `.forgeloop/locks/<taskKey>.lock` using
    atomic creation flags (`wx`). Concurrent mutations on the same task reject with
    `E_TASK_LOCKED`. Read-only commands (`status`, `audit`, `inspect`, `continuity`) bypass
-   locking. Stale locks can be cleared with `forgeloop task-unlock --task <id> --force`.
+   locking. Lock inspection distinguishes `NONE`, `LIVE`, `STALE`, `UNKNOWN`,
+   and `CORRUPT`; unknown or corrupt ownership fails closed. Stale-only release
+   compares the observed lock ID, heartbeat, and owner instance before deletion.
+
+   Recovery that changes claim ownership acquires the project claims lock before
+   the task lock, safely settles an unchanged stale lease, then revalidates phase,
+   work-state revision, ledger sequence, and the `STALE`/`ABANDONED` allowlist
+   before committing `recovery.json` and its append-only event in one transaction.
+   The project claims lock itself uses the same `NONE`/`LIVE`/`STALE`/`UNKNOWN`/
+   `CORRUPT` lease classification and CAS-safe quarantine/restore semantics;
+   unknown, corrupt, or concurrently replaced ownership fails with
+   `E_PROJECT_CLAIMS_LOCK_INCONSISTENT`.
+   The standalone acknowledgement flag does not grant host authority:
+
+   ```text
+   --acknowledge-recovery
+   ≠
+   HOST_ATTESTED
+   ```
+
+   `forgeloop next --task <id> --json` maps conflict evidence to structured
+   `RECONCILE_CLOSURE`, `RECOVER_TASK`, `RESUME_RECOVERED_TASK`, or
+   `RESOLVE_RECOVERY_INCONSISTENCY` guidance. A `RECOVERABLE` task must use its
+   canonical reconciliation path and cannot release claims through `task-recover`.
 
 4. **Task Resolution & Legacy Migration**:
    Commands select their target task via `--task <id>`, the `FORGELOOP_TASK` environment
-   variable, or implicit single-task fallback. If multiple active tasks exist without a
-   selector, ForgeLoop fails closed with `E_TASK_AMBIGUOUS`. Legacy ForgeLoop 1.0 single-task
+   variable, or implicit single-task fallback. Only mutation-active tasks are
+   implicit candidates; recovered, inconsistent, and `COMPLETE` tasks remain
+   explicitly addressable but do not make unrelated work ambiguous. If multiple
+   mutation-active tasks exist without a selector, ForgeLoop fails closed with
+   `E_TASK_AMBIGUOUS`. Legacy ForgeLoop 1.0 single-task
    layouts can be migrated into namespaced layout using `forgeloop task-migrate`.
+
+A project containing active task recovery state requires ForgeLoop 1.4.0 or
+newer.
+<a id="FL-CLAIM-002"></a> **FL-CLAIM-002 — Harnesses that cannot validate task-recovery schema v1 and its linked ledger history MUST refuse**
+ownership mutation rather than fall back to descriptor-only claims.

package/LOOP_SYSTEM_DESIGN.md

@@ -218,6 +218,16 @@ The threat model records path, symlink, artifact, secret, stale-state,
 publication, schema, dependency, and resource-limit boundaries with their
 mitigations, residual limitations, and executable evidence.
 
+Persistent task mutations use a task lease lock and a recoverable transaction
+journal. State writes carry a monotonically increasing revision, while event
+appends are serialized and hash chained. The ledger keeps a validated tail
+checkpoint (`seq` and last hash), so a normal append stages and publishes only
+its new NDJSON suffix; a mismatched tail forces a full checkpoint rebuild. A
+crash during a multi-file publish leaves a journal that `doctor --fix` can roll
+back deterministically — including truncating an interrupted ledger suffix to
+its recorded pre-append size. It never permits a partial artifact set to be
+presented as a completed protocol state.
+
 ### `ENG/*.md`
 
 Nine canonical guides cover:
@@ -370,12 +380,33 @@ registry. If it is not available yet, the same commands can run as
 documents into `.forgeloop/kit/`, keeps only native instruction shims at the
 target root, and leaves project-scoped configuration under `.forgeloop/` while
 isolating modern mutable task protocol state (contract, route, gate, state,
-event, preflight, and receipt artifacts) under
+event, preflight, receipt, and recovery artifacts) under
 `.forgeloop/task-state/<taskKey>/`. Legacy singleton artifacts remain under
 `.forgeloop/` for compatibility and migration only. Manual copying must
 preserve that target layout; copying package-source root files directly is not
 equivalent to `forgeloop init`.
 
+Recovery uses a relational state model: `work-state.json` owns the lifecycle
+phase, `task.json` retains historical claims, `recovery.json` records current
+suspension, and the complete hash-chained ledger proves recovery/resume cycles.
+Only their canonical validated projection can release effective claims. The
+same holds for completion: `RELEASED_BY_COMPLETION` requires the canonical
+completion ownership proof (COMPLETE phase plus a validated ledger containing
+the task-bound `COMPLETION_VALIDATED` event with coherent state and no
+contradicting later lifecycle event); a manually forged COMPLETE state is
+`INCONSISTENT`, retains historical claims, and disables mutation. Any
+missing, corrupt, forged, or mismatched relationship is `INCONSISTENT`, retains
+historical claims, and disables mutation. Recovery never fabricates completion;
+`task-resume` is the only path that rechecks and reacquires ownership before
+removing the recovery artifact. Project claim serialization always precedes
+the per-task lock for create, scope, recover, and resume operations, and both
+lock classes use lease classification plus CAS-safe stale settlement. Task
+locks additionally require complete owner identity (`taskId`, `lockId`,
+`ownerInstanceId`, `operation`, heartbeat, positive lease): incomplete identity
+classifies `UNKNOWN` and is never eligible for stale release. Implicit task
+selection distinguishes read-only discoverability (`READ`: any single healthy
+task) from mutation authority (`MUTATION`: only operationally active tasks).
+
 The README explains the file set, activation behavior, current/relative/absolute
 target installation, first-run profile flow, local validation commands, and safe
 update practice.

package/PROTOCOL_INTEGRATION.md

@@ -108,6 +108,36 @@ workflows that do not automatically discover one of the default files:
 
 A developer or custom automation can execute ForgeLoop identically to an AI agent.
 
+### Compatibility handshake
+
+Before a harness creates or resumes task state, it can read the complete
+machine-readable compatibility boundary:
+
+```bash
+forgeloop protocol-info --json
+```
+
+When a compatibility change requires persisted state conversion, inspect it
+before writing anything:
+
+```bash
+forgeloop migrate-protocol --to 1 --dry-run --json
+```
+
+`migrate-protocol` accepts only versions with an explicit migration in the
+installed release. Unsupported targets fail without rewriting state. The
+current protocol's only supported conversion is the receipt-backed legacy
+singleton-layout migration; a future protocol version must add its own
+validated migration before it can become an accepted `--to` value.
+
+The response separates package and protocol identity. `packageVersion` is the
+installed CLI version; `readsProtocol` and `writesProtocol` enumerate protocol
+versions supported by this CLI; `readsSchemaVersions` and
+`writesSchemaVersions` map every public artifact schema to its supported
+versions. A harness must not infer compatibility from the package version
+alone, and it must fail closed when its required protocol or schema version is
+absent from the relevant list.
+
 ## CLI resolution policy
 
 Lifecycle-owned protocol state must be managed through the project-local ForgeLoop CLI:
@@ -128,6 +158,7 @@ The following protocol artifacts are strictly owned by ForgeLoop:
 - `.forgeloop/task-state/<taskKey>/work-state.json`
 - `.forgeloop/task-state/<taskKey>/events.ndjson`
 - `.forgeloop/task-state/<taskKey>/execution-receipt.json`
+- `.forgeloop/task-state/<taskKey>/recovery.json`
 - `.forgeloop/task-state/<taskKey>/executions/<executionId>.json`
 - Canonical check, evidence, and terminal-result state
 
@@ -201,6 +232,21 @@ actor claim ≠ operator grant
 Authority cannot be self-issued by the actor consuming it. Boolean fields inside
 verification evidence are not sufficient proof of installation authority.
 
+The same rule applies to claim-release recovery. The standalone
+`--acknowledge-recovery` flag records `CALLER_ACKNOWLEDGED`; it is an explicit
+request, not a host grant. The deprecated `--operator-authorized` spelling is
+only a compatibility alias and has identical caller-acknowledgement semantics.
+`HOST_ATTESTED` recovery metadata is valid only when a host integration supplies
+a trusted grant reference through a boundary the active actor cannot mint or
+replace. The standalone CLI does not expose such a self-attestation option.
+
+Claim ownership is a validated relationship, not an artifact preference.
+<a id="FL-CLAIM-001"></a> **FL-CLAIM-001 — Every harness MUST consume the canonical claim-state resolver**
+over the descriptor, work state, recovery artifact, and complete validated
+recovery history. The resolver retains historical claims and disables mutation
+when that relationship is `INCONSISTENT`; reading `recovery.json` alone is
+non-conforming.
+
 ### Authority provenance
 
 Authority provenance is external to actor-authored project state. An external
@@ -324,4 +370,29 @@ ForgeLoop integrates executable verification rules directly into the lifecycle:
 - **Autonomy Principle**: Non-interactive execution is preserved. Tools, commands, and validators operate unattended with standard input closed and without interactive prompt dependencies.
 - **Baseline Protection**: Re-recording baseline debt mid-task is rejected with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`; only monotonic ratchet-down is allowed during active tasks (`baseline --update`). Explicit re-recording requires `--policy-reset-authorized`.
 - **Semantic Recovery**: `forgeloop next` maps policy findings directly to actionable recovery actions (`RESTORE_POLICY`, `REPAIR_CHECKER`, `REPAIR_POLICY`, `REVERIFY_AFTER_POLICY_CHANGE`, `RESTORE_BASELINE`, `CONTINUE_WITH_EXISTING_BASELINE`, `RESOLVE_INERT_CHECK`).
+- **Claim Recovery**: `forgeloop next` maps validated task ownership to `RECONCILE_CLOSURE`, `RECOVER_TASK`, `RESUME_RECOVERED_TASK`, or `RESOLVE_RECOVERY_INCONSISTENCY`. `task-recover` is restricted to `STALE`/`ABANDONED`; it writes durable `recovery.json` plus an append-only event without changing lifecycle evidence. `task-resume` validates the same ownership projection, safely settles an unchanged stale task lock, reuses canonical scope conflict checks, and removes recovery state transactionally.
 - **Task Scoping**: Task-specific policy snapshots and state live under `.forgeloop/task-state/<taskKey>/` to ensure clean multi-task isolation and cross-harness continuity.
+
+## Structured integration surfaces
+
+When a host provides an official ForgeLoop structured integration, prefer it
+for protocol operations; otherwise use the project-local ForgeLoop CLI. Both
+surfaces execute the same canonical commands and share one protocol authority:
+`.forgeloop/` state written only by ForgeLoop itself.
+
+- `@cassiomc1/forgeloop/integration` (integration API version 1): the
+  transport-neutral programmatic runtime. Domain rejections keep `ok:true`
+  with a non-zero exit code; public error codes are preserved verbatim.
+- `@cassiomc1/forgeloop-mcp` (local stdio MCP): an adapter over the same API.
+  It never edits `.forgeloop/` state directly, never synthesizes authority,
+  and never derives claim ownership outside the canonical resolver
+  (`features.integrationApi.version >= 1` in `protocol-info --json`).
+
+ForgeLoop applicability never depends on MCP availability: instruction-only
+hosts remain fully supported through the CLI and instruction adapters.
+
+`protocol-info --json` advertises claim-recovery capability version 1 under
+`features.taskClaimRecovery`. A project containing active task recovery state
+requires ForgeLoop 1.4.0 or newer.
+<a id="FL-CLAIM-003"></a> **FL-CLAIM-003 — A reader without `validatedClaimProjection=true` MUST fail closed**
+and must not mutate claims.

package/README.md

@@ -4,7 +4,13 @@
   <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" width="100%">
 </p>
 
+[![CodeQL](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml)
+[![Dependency review](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml)
 [![Docs quality](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml)
+[![ForgeLoop audit](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml)
+[![Publish npm package](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml)
+[![Package smoke](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml)
+[![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
 ForgeLoop is a portable, vendor-neutral protocol for AI-assisted development
 and developer workflows. It turns an outcome into a contract, deterministic
@@ -52,6 +58,45 @@ frontmatter. Repository validators keep the catalog and metadata synchronized.
 
 ## Quickstart
 
+### Demonstração em 60 segundos
+
+Em um diretório descartável, inicialize o kit e crie uma tarefa isolada. O
+resultado é determinístico e pode ser inspecionado por qualquer harness
+compatível:
+
+```bash
+npx @cassiomc1/forgeloop init
+forgeloop task-create --task demo --claim src --json
+forgeloop route --task demo --work clean-code --json
+forgeloop preflight --task demo --json
+forgeloop next --task demo --json
+```
+
+O último comando informa a ação segura seguinte; ele não executa código nem
+agenda agentes.
+
+Antes de um harness criar ou retomar uma tarefa, ele pode confirmar a
+compatibilidade pública sem depender de detalhes internos:
+
+<!-- FORGELOOP EXAMPLE: readme:compatibility | exit=0 | json.protocolVersion=1 -->
+```bash
+forgeloop protocol-info --json
+```
+<!-- END FORGELOOP EXAMPLE -->
+
+### Responsabilidades
+
+| Responsabilidade | ForgeLoop | Harness ou desenvolvedor |
+| --- | --- | --- |
+| Validar contrato e rotas | Sim | Fornece intenção e sinais |
+| Implementar código | Não | Sim |
+| Registrar proveniência de comando | Sim, com `run-check` | Fornece comando e ambiente |
+| Validar conclusão | Sim | Fornece trabalho e evidência reais |
+| Agendar agentes ou inferência LLM | Não | Externo ao protocolo |
+
+Para uma troca concreta entre ferramentas, veja a
+[continuidade entre harnesses](./docs/CROSS_HARNESS_CONTINUITY.md).
+
 From a published package, initialize a target project with:
 
 ```bash
@@ -150,6 +195,15 @@ forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --
 # List active and completed tasks
 forgeloop task-list --json
 
+# Ask for deterministic conflict/recovery guidance
+forgeloop next --task auth-feature --json
+
+# Only for a task classified STALE or ABANDONED: release effective claims
+forgeloop task-recover --task auth-feature --acknowledge-recovery --json
+
+# Reacquire conflict-free claims before mutating a recovered task again
+forgeloop task-resume --task auth-feature --json
+
 # Run standard lifecycle commands targeting the task
 forgeloop route --task auth-feature --work clean-code --surface backend
 forgeloop preflight --task auth-feature --json
@@ -160,6 +214,16 @@ forgeloop complete --task auth-feature --json
 forgeloop task-migrate --json
 ```
 
+Recovery is not completion. Effective claims become empty only when the
+canonical claim-state resolver validates the relationship between `task.json`,
+`work-state.json`, `recovery.json`, and the complete hash-chained recovery
+history. Fake, missing, corrupt, deleted, or mismatched recovery evidence is
+`INCONSISTENT`: historical claims remain reserved and mutation remains
+disabled. The standalone acknowledgement flag is not host-attested authority.
+`task-resume` removes recovery state only after validated ownership, stale-lock
+settlement, normal claim-overlap, and clean-checkout checks succeed. Never
+create, edit, or delete `recovery.json` manually.
+
 ### Executable policy verification & brownfield baselines
 
 ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
@@ -227,6 +291,11 @@ Consumers must reject unknown artifact fields rather than silently treating
 unrecognized protocol data as valid. The compatibility marker is
 [`tests/fixtures/compatibility/protocol-v1.json`](./tests/fixtures/compatibility/protocol-v1.json).
 
+A project containing active task recovery state requires ForgeLoop 1.4.0 or
+newer. A reader that does not advertise
+`features.taskClaimRecovery.validatedClaimProjection=true` must fail closed;
+it must not infer current ownership from `task.json` or `recovery.json` alone.
+
 ## Security and dependency boundary
 
 The runtime uses Node built-ins only and does not install agents, providers,
@@ -240,6 +309,9 @@ repository policy allows only ESLint, c8, and Mermaid CLI as development
 dependencies; `npm run dependency:policy` fails if runtime or unapproved
 dependencies appear.
 
+Para reportar vulnerabilidades ou contribuir com alterações, consulte
+[`SECURITY.md`](./SECURITY.md) e [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
 ## Autonomous blind-run isolation
 
 The repository does not claim a live blind conformance result for an external
@@ -330,3 +402,17 @@ Task-scoped mutable protocol state is stored under
 
 For document ownership, guide routing, capability degradation, and integration
 details, start at [`DOCS_INDEX.md`](./DOCS_INDEX.md).
+
+## Programmatic integration and MCP
+
+ForgeLoop exposes a stable programmatic surface:
+
+```js
+import { executeForgeLoopCommand } from "@cassiomc1/forgeloop/integration";
+```
+
+The local MCP server (`@cassiomc1/forgeloop-mcp`, stdio) is an adapter over
+this exact API — it never reimplements ForgeLoop. See
+[`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) and
+[`docs/MCP.md`](./docs/MCP.md). MCP is optional; the CLI and instruction-only
+hosts remain fully supported without it.

package/TERMINOLOGY.md

@@ -18,9 +18,24 @@
 | Runtime | A process that owns execution, scheduling, model calls, or persistence; `ForgeLoop` intentionally does not provide one. |
 | 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. |
+| Integration API | The stable programmatic surface (`@cassiomc1/forgeloop/integration`) used by structured consumers instead of parsing CLI output. |
+| MCP adapter | The local-first Model Context Protocol server package; an adapter over canonical ForgeLoop commands, never a second implementation. |
+| Server mode | The MCP launch policy tier (`readonly`, `safe`, `full`) that determines which tool classes are available. |
+| Launch capability | A process-scoped, immutable MCP flag (`--allow-*`) required by higher-risk invocation classes; tool input cannot grant it. |
+| Claim state | Canonical ownership classification (`ACTIVE`, `RELEASED_BY_COMPLETION`, `RELEASED_BY_RECOVERY`, `INCONSISTENT`) produced only by the validated claim resolver. |
+| Historical write claims | Claims recorded as evidence in the task descriptor/recovery history after validated release. |
+| Effective write claims | The claims currently enforced against overlapping acquisition; empty only for validated completion or recovery. |
+| Completion ownership proof | The validated lifecycle/ledger evidence (canonical `COMPLETION_VALIDATED` + coherence) required before COMPLETE releases claims. |
+| Caller acknowledgement | Explicit current-caller authorization for recovery actions; never equivalent to host attestation. |
+| Legacy recovery migration | The narrow append-only repair that materializes one recognized historical recovery boundary into the modern durable representation. |
 | 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`). |
+| Recovered task | A non-terminal task whose ordinary mutation authority is suspended and whose effective write claims are released by durable `recovery.json` state. |
+| Recovery acknowledgement | A caller declaration that it intends to recover a task classified `STALE` or `ABANDONED`; it is not a host-attested authority grant. |
+| Historical claims | The write claims retained in `task.json` as task history, including while recovery releases their active ownership. |
+| Effective claims | The claims currently enforced for ownership conflicts: descriptor claims for an active task, or an empty set after validator-backed completion or active recovery. |
+| Claim reacquisition | The serialized `task-resume` operation that rechecks conflicts and checkout cleanliness before removing recovery state and restoring mutation authority. |
 
 | Execution continuity | Bounded current-task implementation context used to resume the same ForgeLoop task across sessions or harnesses. |
 | Continuity artifact | `.forgeloop/continuity.json`; non-evidence operational context bound to canonical work state. |

package/THIRD_PARTY_NOTICES.md

@@ -195,3 +195,18 @@ The contextual frontend taste guide is informed by Taste Skill:
 ForgeLoop includes a short, adapted guide under `ENG/taste-frontend-eng.md`.
 It does not vendor upstream runtime code, depend on its repository at runtime,
 or make its prescriptive examples universal.
+
+## Runtime dependencies with upstream notices
+
+### Model Context Protocol SDK (MCP package only)
+
+- Packages: `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
+  (test/smoke only), used by `integrations/mcp`. Published from the canonical
+  upstream repository:
+  [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk).
+- License declared by the upstream project: MIT.
+- Use in this collection: official SDK transport/server primitives for the
+  local stdio ForgeLoop MCP adapter.
+- Boundary: the ForgeLoop core package (`@cassiomc1/forgeloop`) has no
+  dependency on the MCP SDK; the SDK ships only inside
+  `@cassiomc1/forgeloop-mcp`. Review upstream terms before redistribution.