@cassiomc1/forgeloop 1.3.0 → 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/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

@@ -20,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 |
@@ -46,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/) |
@@ -57,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
@@ -66,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

@@ -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

@@ -380,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

@@ -158,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
 
@@ -231,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
@@ -354,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

@@ -195,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
@@ -205,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:
@@ -272,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,
@@ -378,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.

package/THREAT_MODEL.md

@@ -18,7 +18,26 @@ remaining trust boundaries and their executable evidence.
 | 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` |
 | Concurrent protocol mutation | Two writers read the same state or ledger tail and silently overwrite each other | Task state, task event ledger, and transaction journal | Mutations acquire a lease-bearing task lock, stage writes in `.forgeloop/.txn/`, preserve a recovery manifest, and publish only after the callback completes; state mutators use an expected revision, while ledger appends validate a tail checkpoint and stage only a synchronized suffix | The filesystem does not provide a multi-file atomic commit primitive; a process killed during append is recovered by truncating to the journaled pre-append size rather than treated as complete | `tests/state-revision.test.js`, `tests/concurrent-ledger.test.js`, `tests/scale-ledger.test.js`, `tests/transaction.test.js` |
-| Stale lock theft | A live process loses exclusive ownership because another process removes its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection classifies `LIVE`, `STALE`, or `UNKNOWN`; ordinary recovery releases only an expired lease and `--force` is explicit | A malicious or separately privileged actor can still delete local locks | `tests/task-cli.test.js`, `tests/task-foundation.test.js` |
+| Stale lock theft | A live process loses exclusive ownership because another process removes or replaces its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection distinguishes `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; stale-only release quarantines the observed inode and compares lock ID, heartbeat, and owner instance before deletion | A malicious or separately privileged actor can still delete local locks; an expired lease remains a recovery heuristic rather than remote liveness proof | `tests/task-lock.test.js`, `tests/task-recover.test.js` |
+| Forged recovery tombstone | A schema-valid fake `recovery.json` makes historical claims disappear without an official recovery event | Task descriptor, recovery artifact, and complete event ledger | The canonical claim-state resolver releases claims only when every artifact field matches one unresolved recovery history cycle; a tombstone alone is `INCONSISTENT`, retains historical claims, and disables mutation | A privileged actor can replace every linked local artifact; validation proves consistency, not remote attestation | `tests/task-claim-state.test.js`, `tests/task-claim-ownership-integration.test.js`, `tests/task-recovery-invariants.test.js` |
+| Forged completion claim release | An actor changes `work-state.phase` to `COMPLETE` to make write claims disappear without canonical completion | Work state, canonical completion event, and the complete validated event ledger | Claim ownership releases COMPLETE claims only when state and a validated lifecycle ledger prove canonical completion (`COMPLETION_VALIDATED` bound to the task, coherent state/ledger, no contradicting later lifecycle event); otherwise ownership is `INCONSISTENT` with historical claims retained, mutation disabled, and overlapping acquisition blocked (`E_COMPLETION_OWNERSHIP_UNPROVEN`) | A separately privileged actor can rewrite all local artifacts consistently; ForgeLoop provides consistency verification, not external cryptographic attestation | `tests/completion-claim-ownership.test.js`, `tests/task-claim-state.test.js` |
+| Incomplete task-lock identity theft | A structurally incomplete persisted task lock (missing lockId, owner instance, operation, or lease) with plausible timestamps is classified LIVE/STALE and removed as stale | `.forgeloop/locks/<taskKey>.lock` identity validation | Task lock identity requires `taskId`, `lockId`, `ownerInstanceId`, `operation`, heartbeat, and a positive integer lease; incomplete metadata classifies `UNKNOWN` (never stale-releasable), lease values are never defaulted at validation time, and CAS release additionally requires `lock.taskId === requested taskId` plus unchanged observed identity | A privileged writer can still forge a fully identified lock; classification proves structure, not liveness | `tests/task-lock.test.js` |
+| Partial already-repaired relationship | A tampered recovery artifact (claims, classification, revision, fingerprint, or authority edited after migration) is accepted as an idempotent already-repaired no-op | Full canonical relationship validation in `alreadyRepaired` | Idempotency requires the complete validated ownership projection (`RELEASED_BY_RECOVERY` with matching recovery id/seq) and every artifact field agreeing with the canonical migration event; any mismatch fails closed | A separately privileged actor can rewrite all local artifacts consistently; validation proves consistency, not attestation | `tests/task-repair-legacy-recovery.test.js` |
+| Forged legacy-migration authority | A forged `LEGACY_RECOVERY_MIGRATION_RECORDED` claims `HOST_ATTESTED` authority to impersonate a host grant | Migration event authority validation | Legacy migration v1 accepts only `CALLER_ACKNOWLEDGED`; any other authority kind makes the event invalid and the ledger INCONSISTENT | Normal recovery events retain their own host-attestation boundary with trusted grant references | `tests/task-repair-legacy-recovery.test.js` |
+| MCP project-root substitution | A tool call supplies a different project root to read or mutate an unintended target | Immutable server-pinned project context | The ForgeLoop MCP server realpaths the project root once at startup and freezes it; project root is never a tool input | A privileged local process can still target other roots by launching its own server | `integrations/mcp/tests/` |
+| MCP claim-projection fork | An adapter derives claim ownership from raw artifacts (task.json, recovery.json) and disagrees with the canonical resolver | Canonical ownership resource | The `task/ownership` resource is derived exclusively from `resolveTaskClaimState()`; forged COMPLETE stays INCONSISTENT with retained claims through the resource surface | Presentation bugs could still mislabel values; the resolver remains the single authority | `integrations/mcp/tests/ownership.test.js`, `tests/integration-resources.test.js` |
+| MCP capability escalation via tool input | Tool input (e.g. `force: true`, `acknowledgeRecovery: true`) elevates a server started without the matching capability | Launch-level capability gates re-checked per invocation | Risk classification is invocation-level; disabled capabilities refuse with `E_MCP_CAPABILITY_DISABLED`; recovery acknowledgement never upgrades launch policy; legacy repair stays hidden by default; deprecated `operatorAuthorized` is absent from schemas | A separately authorized local actor can restart the server in full mode | `integrations/mcp/tests/policy.test.js`, `integrations/mcp/tests/safety.test.js` |
+| MCP HTTP unauthenticated remote bind | A network-bound MCP endpoint exposes ForgeLoop operations to any reachable client without authentication | Loopback-only bind policy | The HTTP transport refuses every non-loopback bind with `E_MCP_REMOTE_NOT_SUPPORTED`; Host/Origin validation is defense against DNS rebinding, not authentication; remote access stays disabled until a separately designed authenticated boundary exists | A same-host process can still reach the loopback endpoint | `integrations/mcp/tests/http.test.js` |
+| MCP protocol downgrade / legacy fallback | Legacy-era traffic is silently served, weakening the declared 2026 security posture | Strict modern mode | The HTTP handler is constructed with the SDK strict-modern setting (`legacy: "reject"`); legacy handshakes are answered with an unsupported-protocol-version rejection instead of being served | Stdio remains available for clients that only speak older protocol generations | `integrations/mcp/tests/http.test.js` |
+| MCP HTTP resource exhaustion | Slow headers, slow bodies, oversized bodies, or connection floods exhaust server resources | Bounded transport controls | Header/request/keepalive timeouts are set on the HTTP server; request bodies are hard-bounded at 4 MiB (413 on exceed); an in-flight ceiling sheds load with 503 `E_MCP_HTTP_BUSY`; only POST is served | Bounds protect availability, not authorization | `integrations/mcp/tests/http.test.js` |
+| Transport metadata as authority | An MCP session id, HTTP source address, Origin/Host header, or tool-supplied acknowledgement is treated as ForgeLoop authority | Authority-free adapter design | No session identity is issued or consumed; capability policy is fixed at launch and re-checked per invocation; acknowledgement fields satisfy canonical command semantics only after launch-level capability was granted | None within the adapter boundary; host-level network controls remain external | `integrations/mcp/tests/policy.test.js` |
+| MCP stdout corruption / shell injection | Protocol transport polluted by diagnostics, or a generic shell tool enabling arbitrary execution | Transport discipline and exact-argv policy | stdout carries only MCP protocol; logging goes to stderr; no shell/exec tools exist; external execution passes exact argv arrays through canonical provenance | Compromised dependencies remain out of scope of transport discipline | `scripts/mcp-package-smoke.mjs` |
+| Recovery tombstone deletion / claim resurrection | Deleting `recovery.json` lets a recovered task mutate after another task adopts the released scope | Recovery history and all ordinary task mutation entry points | The complete ledger derives unresolved recovery independently; a missing tombstone with unresolved history is `INCONSISTENT`, and the canonical mutation guard rejects it with `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT` | A separately privileged process can still deny service by corrupting local artifacts | `tests/task-claim-state.test.js`, `tests/task-claim-ownership-integration.test.js` |
+| Corrupt task namespace claim disappearance | An unreadable descriptor or recovery artifact is interpreted as claim-free during task creation or scope change | Modern task namespace discovery and project claim acquisition | Readable historical claims are retained conservatively; an unhealthy namespace with unknown ownership blocks claim mutation globally with `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT` | Recovery requires repairing protocol-owned evidence; ForgeLoop does not invent unknown claims | `tests/task-claim-ownership-integration.test.js`, `tests/task-recovery-tamper.test.js` |
+| Recovery event-tail eviction | Later ledger events push recovery history beyond a bounded read window and reactivate old claims | Recovery state versus append-only event history | Claim ownership validates the complete ledger and binds the artifact to its exact recovery event, recovery ID, claims, classification, authority, revision, and repository fingerprint | Full validation is intentionally correctness-first and may be optimized only with verdict-equivalent checkpoints | `tests/task-recover.test.js`, `tests/task-recovery-validation.test.js`, `tests/task-recovery-invariants.test.js` |
+| Project claims lock deadlock or theft | A crashed process blocks every ownership transition, or stale cleanup removes a replacement owner | `.forgeloop/.claims.lock` | Project claim locks classify `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; acquisition may quarantine and remove only an unchanged stale inode after matching lock ID, heartbeat, and owner instance, while unknown/corrupt/CAS-mismatch state fails closed | Lease expiry is a recovery heuristic; separately privileged filesystem writers remain outside the boundary | `tests/project-claims-lock.test.js`, `tests/task-recovery-concurrency.test.js` |
+| Self-asserted recovery authority | An actor labels its own recovery request operator- or host-authorized | Caller input, recovery authority metadata, and host integration boundary | Standalone recovery records only `CALLER_ACKNOWLEDGED`; the deprecated operator flag is only an alias; `HOST_ATTESTED` requires a host-owned grant reference and cannot be minted by the CLI | Host attestation remains only as strong as the host-controlled boundary and grant source | `tests/task-recovery-cli.test.js`, `tests/task-recovery-validation.test.js` |
+| Recovery TOCTOU and reacquisition collision | State changes between inspection and claim release, or two tasks acquire the same released path | Project claims lock, task lock, revision, ledger sequence, and scope checks | Project-claims lock precedes task lock; recovery revalidates validated ownership, classification, revision, phase, and ledger sequence; resume validates the same ownership, CAS-settles stale task locks, and reuses normal conflict and clean-scope enforcement; concurrent tests assert at most one active owner | The filesystem cannot make repository content and multi-file metadata globally atomic against separately privileged writers | `tests/task-recovery-concurrency.test.js`, `tests/project-claims-lock.test.js`, `tests/task-lock.test.js`, `tests/task-resume.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` |

package/docs/ARTIFACT_REFERENCE.md

@@ -30,6 +30,7 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `policy/baseline.json` | `policy-baseline` | Protocol Generated Or Operator | Monotonic Ratchet Down | Brownfield Baseline |
 | `policy/policy.lock` | `policy-lock` | Protocol Generated | Atomic Digest Compilation | Policy Integrity Lock |
 | `task-state/<task-key>/policy-snapshot.json` | `policy-snapshot` | Protocol Generated | Mutable Before Execution | Task Policy Attestation |
+| `task-state/<task-key>/recovery.json` | `task-recovery` | Protocol Generated | Recovery State Transitions | Task Recovery State |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -601,3 +602,45 @@ comparison explicitly `UNKNOWN` rather than assuming an empty baseline.
 - `capturedAt` *(string, optional)*
 
 <!-- END FORGELOOP GENERATED: schema:policy-snapshot -->
+
+---
+
+### 2.19 `task-state/<taskKey>/recovery.json`
+
+<!-- forgeloop-doc: schema=task-recovery artifact=.forgeloop/task-state/<task-key>/recovery.json -->
+
+Durable current-state input for claim-release recovery. It records the
+classification and exact claims released while leaving lifecycle work state,
+receipts, failures, policy, and continuity unchanged. Structural validity alone
+does not release claims: ForgeLoop must also validate the descriptor, work
+state, full ledger, referenced recovery event, and absence of a later matching
+resume. A mismatch is `INCONSISTENT`, preserves historical claims, and suspends
+ordinary mutation until the protocol-owned evidence is repaired.
+
+`CALLER_ACKNOWLEDGED` is not host attestation. `HOST_ATTESTED` requires a
+host-owned `grantRef`; the standalone CLI does not self-issue that authority.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:task-recovery -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `status` *(string, required, const: `RECOVERED`)*
+- `recoveredAt` *(string, required)*
+- `recoveryId` *(string, required, pattern: `^recovery-[A-Za-z0-9-]+$`)*
+- `recoveryEventSeq` *(integer, required, minimum: 1)*
+- `classificationAtRecovery` *(string, required, enum: `STALE`, `ABANDONED`, `LEGACY_BOUNDARY_MIGRATED`)*
+- `reasonCodes` *(array<string>, required)*
+- `releasedClaims` *(array<string>, required)*
+- `previousPhase` *(string, required, minLength: 1)*
+- `previousRevision` *(integer, required, minimum: 0)*
+- `repositoryFingerprint` *(object, required)*
+  - `branch` *(string,null, required)*
+  - `head` *(string,null, required)*
+- `authority` *(object, required)*
+  - `kind` *(string, required, enum: `CALLER_ACKNOWLEDGED`, `HOST_ATTESTED`)*
+  - `grantRef` *(string, optional, minLength: 1)*
+
+<!-- END FORGELOOP GENERATED: schema:task-recovery -->

package/docs/CLI_REFERENCE.md

@@ -40,7 +40,7 @@ ForgeLoop uses a definition-driven command-line parser:
 | Category | Commands |
 | --- | --- |
 | **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock) |
+| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
 | **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt) |
@@ -1263,9 +1263,9 @@ protocol version.
 
 ### `task-unlock`
 
-Forces the release of a stale task lock.
+Forces the release of a task lock or CAS-safely releases an unchanged stale lease.
 
-- **Purpose**: Removes `.lock` file from the task directory when process crashed.
+- **Purpose**: Removes `.forgeloop/locks/<taskKey>.lock` when its owner is no longer valid. Prefer `--stale-only`; `--force` is an explicit unconditional maintenance action.
 - **Mutation**: Deletes task lock file.
 - **Options**:
 
@@ -1284,3 +1284,97 @@ Forces the release of a stale task lock.
   ```bash
   forgeloop task-unlock --task task-001 --force --json
   ```
+
+### `task-recover`
+
+Suspends mutation and releases effective claims for a task deterministically classified `STALE` or `ABANDONED`.
+
+- **Purpose**: For a task classified only `STALE` or `ABANDONED`, persists `recovery.json` plus a linked append-only event without changing work state or fabricating completion. The canonical claim-state resolver must validate both before claims become effective-empty. `RECOVERABLE` tasks must use `reconcile-closure`.
+- **Mutation**: Transactionally writes recovery state and appends the recovery event. Historical descriptor claims and all lifecycle evidence remain intact; ordinary mutations return `E_TASK_RECOVERED`.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-recover:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-recovery`: acknowledge release of claims for a STALE or ABANDONED task (required; not host attestation)
+- `--operator-authorized`: deprecated alias for --acknowledge-recovery; does not attest operator authority
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-recover:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-recover --task task-001 --acknowledge-recovery --json
+  ```
+
+`--acknowledge-recovery` is caller acknowledgement only. The deprecated
+`--operator-authorized` alias has the same semantics and is not host attestation.
+Fake, missing, corrupt, or mismatched recovery state is
+`E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`/`E_TASK_RECOVERY_INCONSISTENT`; historical
+claims remain reserved.
+
+### `task-resume`
+
+Reacquires a recovered task's write claims and restores ordinary mutation authority.
+
+- **Purpose**: Validates active recovery ownership, CAS-settles only an unchanged stale task lease, reuses normal claim-overlap and clean-checkout enforcement under project/task serialization, then removes `recovery.json` transactionally.
+- **Mutation**: Optionally updates historical claims in `task.json`, appends `TASK_RECOVERY_RESUMED`, and removes `recovery.json` in one transaction.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--claim <path>`: write claim to reacquire (defaults to all released claims) (repeatable)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-resume:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-resume --task task-001 --claim src --claim tests --json
+  ```
+
+With no `--claim`, the command attempts to reacquire all claims recorded in the
+active recovery artifact. It returns `E_TASK_SCOPE_CONFLICT` without removing
+recovery state when another active task owns an overlapping path.
+The resume event counts as meaningful task activity. Never create, edit, or
+delete `recovery.json` manually to emulate this command.
+
+### `task-repair-legacy-recovery`
+
+Migrates one recognized legacy recovery boundary event into the modern durable recovery representation.
+
+- **Purpose**: Proves that a historical `OPERATOR_RECOVERY_RECORDED` without `recoveryId` marks the effective task boundary and materializes its modern representation as an append-only `LEGACY_RECOVERY_MIGRATION_RECORDED` event plus a transactional `recovery.json`. The original legacy event is never modified.
+- **Mutation**: Appends the migration event at the ledger tail and writes `recovery.json` in one transaction under project claims locking.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-repair-legacy-recovery:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-recovery`: fresh explicit acknowledgement of the legacy boundary migration (required)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-repair-legacy-recovery:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-repair-legacy-recovery --task task-001 --acknowledge-recovery --json
+  ```
+
+Only the exact known legacy signature is eligible; ambiguous, tampered, or
+post-boundary-active ledgers fail closed with
+`E_LEGACY_RECOVERY_MIGRATION_INVALID` and ownership stays INCONSISTENT. A
+`STALE` task lease is settled only through CAS-safe stale release when the
+observed lock is unchanged; `LIVE` locks refuse with `E_TASK_LOCKED`, and
+`UNKNOWN`/`CORRUPT` locks fail closed with the lock preserved — never delete a
+lock file manually to unblock this command. The repair is idempotent: an
+already repaired task returns `{repaired: 0, alreadyRepaired: true}` only when
+the whole canonical recovery relationship validates; any mismatch fails closed.
+The repair itself never releases claims directly; ownership becomes validated
+recovery state and ordinary mutation remains blocked until `task-resume`.