@cassiomc1/forgeloop 1.3.0 → 1.5.0

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -54,6 +54,7 @@ Key continuity invariants:
 | --- | --- | --- | --- |
 | **Task Descriptor** | `.forgeloop/task-state/<taskKey>/task.json` | Task ID, write claims, and task registration | Descriptor authority |
 | **Lifecycle Checkpoint** | `.forgeloop/task-state/<taskKey>/work-state.json` | Current phase, cycle, active guides, preflight binding | Canonical lifecycle truth |
+| **Recovery State** | `.forgeloop/task-state/<taskKey>/recovery.json` | Candidate current suspension bound to ledger history | One input to canonical validated claim ownership; never sufficient alone and never completion evidence |
 | **Operational Continuity** | `.forgeloop/task-state/<taskKey>/continuity.json` | Active focus, remaining items, known issues, inspect-first paths | Operational context only (non-evidence) |
 | **Implementation Truth** | Git checkout / filesystem | Actual source code and files | Ground truth for changes |
 | **Task Intent** | `.forgeloop/task-state/<taskKey>/contract.json` | Objectives, constraints, deliverables, verification requirements | Contract authority |
@@ -182,6 +183,26 @@ forgeloop next --task auth-feature --json
 
 Follow the deterministic action returned by ForgeLoop (e.g. `CONTINUE_IMPLEMENTATION`, `ENTER_VERIFYING`, or `RECORD_CHECK`).
 
+If `next` returns `RESUME_RECOVERED_TASK`, the handoff is still the same task,
+but ordinary mutation is suspended. Inspect the recovery metadata and current
+claim owners, then reacquire claims explicitly:
+
+```bash
+forgeloop task-show --task auth-feature --json
+forgeloop task-resume --task auth-feature --json
+```
+
+Do not create, edit, or delete `recovery.json` manually. Every harness must use
+the canonical validated descriptor + work-state + recovery + ledger projection;
+a tombstone alone never releases claims. If another task owns an
+overlapping path, `task-resume` fails with `E_TASK_SCOPE_CONFLICT` and leaves
+the recovery state intact.
+
+A project containing active task recovery state requires ForgeLoop 1.4.0 or
+newer and `features.taskClaimRecovery.validatedClaimProjection=true` in
+`protocol-info`. An unaware reader must fail closed rather than continue from
+descriptor-only ownership.
+
 ---
 
 ## 6. Stale, Inconsistent, or Missing Handoffs
@@ -197,6 +218,8 @@ ForgeLoop handles edge cases deterministically:
 | **Multiple Active Tasks** | No `--task` or `FORGELOOP_TASK` supplied | `E_TASK_AMBIGUOUS` | List tasks with `task-list` and supply `--task` |
 | **Different Task ID** | Contract / state ID mismatch | `TASK_MISMATCH` | Do not merge contexts; complete or clear previous state |
 | **Malformed State** | Corrupted JSON or invalid hash chain | `INVALID` | Fails closed; inspect errors via `forgeloop doctor --json` |
+| **Recovered Task** | `recovery.json` and its complete ledger history validate as one active recovery cycle | `RESUME_RECOVERED_TASK` | Inspect ownership, then use `task-resume`; recovery is not completion |
+| **Recovery Inconsistency** | Artifact/history, descriptor claims, lock, or ledger evidence is missing, corrupt, or mismatched | `RESOLVE_RECOVERY_INCONSISTENCY` | Historical claims remain reserved; run `validate-protocol` and repair the named artifact instead of forcing recovery |
 
 ---
 

package/docs/DOCUMENTATION_GUIDE.md

@@ -31,10 +31,24 @@ Reason-code truth       -> exported protocol constants (src/core/error-codes.js,
 Guide registry truth    -> canonical guide registry (src/config/guides.json)
 Package contents truth  -> package.json + package tests (tests/package.test.js)
 Documentation routing   -> DOCS_INDEX.md
+Integration API truth   -> src/integration.js (exports, envelope, limits, risk classes, resources)
+MCP behavior truth      -> integrations/mcp/src/* and integrations/mcp/package.json
+MCP package boundary    -> MCP package tests + scripts/mcp-package-smoke.mjs
 ```
 
 Operational documentation must explain canonical behavior, not redefine it.
 
+Documentation-impact questions for integration/MCP changes:
+
+- Did a server mode or capability gate change?
+- Did an MCP transport change?
+- Did an adapter error code change?
+- Did an integration limit or resource list change?
+
+Anti-drift invariant: every `documentation-manifest.json` entry marked
+`packaged: true` is mechanically checked against the core npm tarball
+contents (`tests/package.test.js`).
+
 Canonical phase and transition inventories must be derived from `WORK_PHASES`
 and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
 enums when a generated or mechanically validated representation is available.

package/docs/GETTING_STARTED.md

@@ -382,6 +382,7 @@ forgeloop task-migrate --json
 ## 8. Next Steps
 
 - Continue a task across different AI harnesses: [`docs/CROSS_HARNESS_CONTINUITY.md`](./CROSS_HARNESS_CONTINUITY.md)
+- Optional: use ForgeLoop through MCP or the Integration API — [`docs/MCP.md`](./MCP.md) and [`docs/UNIVERSAL_INTEGRATION.md`](./UNIVERSAL_INTEGRATION.md). MCP is not required; CLI and MCP share the same canonical project/task state.
 - Complete command reference: [`docs/CLI_REFERENCE.md`](./CLI_REFERENCE.md)
 - Artifact and schema reference: [`docs/ARTIFACT_REFERENCE.md`](./ARTIFACT_REFERENCE.md)
 - Common symptoms and recovery: [`docs/TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)

package/docs/MCP.md

@@ -0,0 +1,126 @@
+# ForgeLoop MCP
+
+The `@cassiomc1/forgeloop-mcp` package is a **local-first MCP adapter** over
+the canonical ForgeLoop integration API (`@cassiomc1/forgeloop/integration`).
+It is an **adapter, never a second implementation**: every tool call executes
+a canonical ForgeLoop command and every ownership value comes from the
+canonical claim resolver.
+
+Two transports ship in one package:
+
+- `forgeloop-mcp` — **stdio**, the default/recommended transport;
+- `forgeloop-mcp-http` — **optional** strict-modern MCP 2026 HTTP,
+  loopback-only (remote access is unsupported).
+
+## Core principles
+
+- **No duplicated protocol logic.** The server contains no lifecycle,
+  ownership, recovery, lock, or transaction code.
+- **No direct protocol-state access.** The adapter never reads or writes
+  `.forgeloop` files; all mutation flows through ForgeLoop's own guards
+  (locks, transactions, revision checks, ledger append serialization).
+- **`COMPLETE` is not enough.** Claim release is presented exactly as the
+  canonical resolver reports it; forged COMPLETE stays INCONSISTENT with
+  historical claims retained.
+- **Recovery acknowledgement is not authorization.** `acknowledgeRecovery`
+  in tool input only satisfies ForgeLoop's caller acknowledgement after the
+  server was started with recovery capability.
+
+## Modes
+
+| Mode | Read | Loop mutations | task-resume | External | Maintenance | Recovery | Legacy repair | Force |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `readonly` | yes | no | no | no | no | no | no | no |
+| `safe` (default) | yes | yes | yes | no | no | no | no | no |
+| `full` | yes | yes | yes | opt-in | opt-in | opt-in | opt-in | opt-in |
+
+Capability flags (process-scoped, immutable after launch):
+`--allow-external-execution`, `--allow-maintenance`, `--allow-recovery`,
+`--allow-legacy-repair`, `--allow-force-recovery`.
+
+## Resources
+
+- `forgeloop://protocol/info`
+- `forgeloop://project/tasks`
+- `forgeloop://task/{taskId}/status`
+- `forgeloop://task/{taskId}/ownership` — canonical validated ownership
+- `forgeloop://task/{taskId}/contract`
+- `forgeloop://task/{taskId}/continuity`
+
+Raw recovery artifacts, transaction journals, lock files, and unbounded event
+ledgers are intentionally not exposed.
+
+## Optional stateless HTTP transport
+
+`forgeloop-mcp-http` serves the same deterministic catalog over the **strict
+modern** stateless MCP 2026 model (legacy-era traffic rejected):
+
+```bash
+forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
+```
+
+- **Loopback only**: non-loopback binds fail closed with
+  `E_MCP_REMOTE_NOT_SUPPORTED`. Authenticated remote access is not designed
+  yet; Host validation is DNS-rebinding defense, not authentication.
+- Strict modern: legacy-era handshakes are rejected, never silently served.
+- Stateless: no session identity is issued, so transport metadata is never
+  ForgeLoop authority.
+- Resource bounds: 4 MiB body cap, POST-only, header/request/keepalive
+  timeouts, in-flight ceiling (503 `E_MCP_HTTP_BUSY`).
+
+## Version matrix
+
+| Component | Current contract |
+| --- | --- |
+| ForgeLoop core package | `1.5.x` repository generation |
+| ForgeLoop protocol | `1` |
+| Integration API | `1` |
+| MCP package | `0.1.x` initial package |
+| MCP protocol target | `2026-07-28` |
+
+Repository implementation is separate from npm publication; nothing here
+claims a published release.
+
+## Risk classes and gating examples
+
+Invocations are classified at the adapter boundary:
+
+```text
+READ_ONLY · LOOP_MUTATION · CLAIM_REACQUISITION · EXTERNAL_EXECUTION
+MAINTENANCE · CLAIM_RELEASE_RECOVERY · LEGACY_MIGRATION · FORCE_DESTRUCTIVE
+```
+
+Examples: `bundle` → MAINTENANCE (hidden in readonly/safe);
+`task-resume` → CLAIM_REACQUISITION (available in safe — canonical claim
+reacquisition); `task-recover` → CLAIM_RELEASE_RECOVERY (full +
+`--allow-recovery`, plus the canonical acknowledgement); legacy repair →
+separately gated/hidden; force unlock → separately gated. Tool input can
+never elevate launch policy.
+
+## Bounds and timeouts
+
+- Structured MCP input is byte-bounded (`E_MCP_INPUT_TOO_LARGE`).
+- External execution cannot exceed the server launch timeout maximum:
+  omitted/null timeout receives the maximum; `0`, negative, non-integer, or
+  above-maximum values are refused.
+- Tool, capabilities and resource output is bounded using the exact UTF-8
+  serialization actually transmitted. Oversized output fails closed with
+  `E_MCP_RESULT_TOO_LARGE` and is never silently truncated.
+
+## Adapter errors
+
+Adapter-level errors are separate from the generated ForgeLoop core error
+list in [TROUBLESHOOTING](./TROUBLESHOOTING.md):
+
+| Code | Meaning |
+| --- | --- |
+| `E_MCP_INPUT_TOO_LARGE` | structured tool input exceeds the byte bound |
+| `E_MCP_RESULT_TOO_LARGE` | serialized output exceeds the output bound |
+| `E_MCP_HTTP_BUSY` | in-flight HTTP ceiling reached (503, Retry-After) |
+| `E_MCP_REMOTE_NOT_SUPPORTED` | non-loopback bind attempted |
+| `E_MCP_EXECUTION_TIMEOUT_INVALID` | timeout not a positive integer |
+| `E_MCP_EXECUTION_TIMEOUT_EXCEEDS_LIMIT` | timeout above server maximum |
+| `E_MCP_FORGELOOP_INTEGRATION_UNSUPPORTED` | installed core integration API mismatch |
+
+Canonical ForgeLoop errors (e.g. `E_TASK_SCOPE_CONFLICT`,
+`E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`) are always preserved verbatim.

package/docs/RECIPES.md

@@ -20,6 +20,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 12. [Migrate Legacy 1.0 Single-Task Layout](#recipe-12--migrate-legacy-10-single-task-layout)
 13. [Record Decision Settlement Criteria](#recipe-13--record-decision-settlement-criteria)
 14. [Executable Policy, Baseline Ratchet, and Recovery](#recipe-14--executable-policy-baseline-ratchet-and-recovery)
+15. [Release and Reacquire Claims for an Abandoned Task](#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
 
 ---
 
@@ -311,3 +312,84 @@ forgeloop next --task task-001 --json
 # Intentional operator-authorized baseline reset (not normal recovery)
 forgeloop baseline --record --policy-reset-authorized --json
 ```
+
+---
+
+### Recipe 15 — Release and Reacquire Claims for an Abandoned Task
+
+```bash
+# 1. Inspect deterministic classification and structured next action
+forgeloop next --task task-001 --json
+
+# 2. RECOVERABLE must use reconcile-closure; do not use task-recover
+forgeloop reconcile-closure --task task-001 --id <verification-id> \
+  --requirement "<exact verification text>" -- <verification-command>
+
+# 3. Only STALE or ABANDONED may release effective claims
+forgeloop task-recover --task task-001 --acknowledge-recovery --json
+
+# 4. Other tasks may now adopt the released paths
+forgeloop task-create --task replacement-task --claim src --json
+
+# 5. Reacquisition fails while replacement-task owns src
+forgeloop task-resume --task task-001 --json
+
+# 6. After the conflicting owner completes, reacquire claims explicitly
+forgeloop task-resume --task task-001 --claim src --json
+```
+
+`--acknowledge-recovery` records caller acknowledgement only. It does not grant
+host authority or mark the task complete. Recovery preserves work state,
+receipts, failures, policy snapshots, and continuity until normal lifecycle
+work resumes. Claims are released only after ForgeLoop validates the recovery
+artifact against the complete ledger history. If `next` returns
+`RESOLVE_RECOVERY_INCONSISTENCY`, run `validate-protocol`; do not create, edit,
+or delete `recovery.json` manually.
+
+## Run ForgeLoop through MCP (safe mode)
+
+Start the local MCP adapter and inspect what it exposes:
+
+```bash
+forgeloop-mcp --project . --mode safe
+```
+
+`safe` mode permits reads, normal loop mutations, and canonical `task-resume`.
+Call the `forgeloop_capabilities` tool first: it reports versions, features,
+launch policy, and the resource list. Task ownership is available from the
+`forgeloop://task/{taskId}/ownership` resource — always the canonical claim
+resolver projection.
+
+## Resume a recovered task through MCP
+
+Recovered tasks stay mutation-disabled until claims are reacquired:
+
+```json
+{ "tool": "forgeloop_task_resume", "arguments": { "taskId": "my-task" } }
+```
+
+Conflicting claims fail with `E_TASK_SCOPE_CONFLICT` and keep recovery intact.
+Ordinary mutations against a recovered task are refused by core regardless of
+transport.
+
+## Deliberately opt into external execution
+
+`run-check`/`reconcile-closure` require a full-mode launch flag; tool input
+cannot grant it:
+
+```bash
+forgeloop-mcp --mode full --allow-external-execution
+```
+
+Execution uses exact argv arrays only — there is no generic shell tool — and
+the server `--max-execution-time-ms` ceiling always applies. Output is bounded
+on the exact UTF-8 serialization transmitted (`E_MCP_RESULT_TOO_LARGE`);
+oversized structured input fails with `E_MCP_INPUT_TOO_LARGE`.
+
+## Diagnose loopback-only HTTP errors
+
+`forgeloop-mcp-http` binds loopback only. A non-loopback bind fails closed
+with `E_MCP_REMOTE_NOT_SUPPORTED`; remote/authenticated HTTP is unsupported.
+Host/Origin validation is DNS-rebinding defense, not authentication. Under
+load, requests beyond the in-flight ceiling receive 503 `E_MCP_HTTP_BUSY`
+with `Retry-After`.

package/docs/RELEASE_CHECKLIST_1_4.md

@@ -0,0 +1,38 @@
+# ForgeLoop 1.4.0 release checklist
+
+This checklist prepares the validated claim-recovery capability for release. It does not authorize publication, tagging, or deployment.
+
+## Ownership and recovery gates
+
+- [ ] Fake, deleted, corrupt, schema-invalid, and mismatched `recovery.json` cases resolve to `INCONSISTENT`.
+- [ ] `INCONSISTENT` preserves historical claims, disables mutation, blocks overlapping acquisition, and is visible in list/show/status/audit/inspect/next.
+- [ ] Only a fully matched recovery artifact and append-only recovery history releases claims.
+- [ ] `task-recover` remains restricted to `STALE` and `ABANDONED`; `RECOVERABLE` keeps its canonical reconciliation path.
+- [ ] `task-resume` validates ownership, settles only an unchanged stale task lock, and reacquires claims under the project claims lock.
+- [ ] Project claim locks classify `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`, with CAS-safe stale settlement.
+- [ ] Manually forged COMPLETE state cannot release claims.
+- [ ] Canonically completed task does release claims.
+- [ ] Corrupt/missing completion lifecycle proof retains historical claims.
+- [ ] Task locks with incomplete identity classify UNKNOWN.
+- [ ] Single COMPLETE/RECOVERED task can be inspected implicitly by READ commands.
+- [ ] Single COMPLETE/RECOVERED task cannot be selected implicitly for mutation.
+- [ ] Ownership ledger validation is not redundantly repeated inside one immutable snapshot.
+- [ ] Legacy recovery repair CAS-settles only unchanged stale task locks.
+- [ ] Legacy recovery repair refuses UNKNOWN/CORRUPT task locks.
+- [ ] alreadyRepaired requires a fully valid canonical recovery relationship.
+- [ ] No exported claim helper releases claims from COMPLETE phase alone.
+- [ ] Legacy recovery migration v1 accepts only CALLER_ACKNOWLEDGED authority.
+
+## Compatibility and package gates
+
+- [ ] `package.json` and `package-lock.json` agree on `1.4.0`.
+- [ ] `protocol-info --json` advertises `features.taskClaimRecovery.validatedClaimProjection=true` and task-recovery schema v1.
+- [ ] Documentation states that active task-recovery schema v1 requires a recovery-aware ForgeLoop reader (`>=1.4.0`).
+- [ ] The packed package contains the recovery schema, claim-state core, recovery-history core, and this checklist.
+- [ ] `npm test && npm run lint && npm run coverage && npm run docs:check && npm run pack:check && npm run pack:smoke && npm run dependency:policy` passes once on the release candidate.
+- [ ] `git diff --check` and the repository ForgeLoop audit pass.
+
+## Publication boundary
+
+- [ ] A separately authorized release workflow verifies the final commit, `v1.4.0` tag, npm metadata, tarball digests, and GitHub release identity.
+- [ ] No actor treats caller acknowledgement as `HOST_ATTESTED` authority.

package/docs/RELEASE_CHECKLIST_1_5_MCP.md

@@ -0,0 +1,78 @@
+# ForgeLoop 1.5.0 + MCP release checklist
+
+Preparation checklist for the `@cassiomc1/forgeloop` 1.5.0 and
+`@cassiomc1/forgeloop-mcp` releases. It does not authorize publication.
+
+## Core integration gates
+
+- [ ] Core package version is `1.5.0`; integration API version is `1`.
+- [ ] `exports` map exposes only `.` and `./integration`.
+- [ ] Executor registry is in parity with canonical command definitions.
+- [ ] `bundle` is MAINTENANCE-gated; hidden in readonly/safe.
+- [ ] `resolveForgeLoopProjectRoot` applies CLI target semantics (symlinks rejected).
+- [ ] Integration limits bound strings, arrays, argv, and structured inputs.
+
+## MCP package gates
+
+- [ ] Official SDK v2; target protocol generation `2026-07-28`.
+- [ ] stdio works with clean stdout (protocol-only) and JSON stderr diagnostics.
+- [ ] HTTP is strict modern (`legacy: "reject"`) and loopback-only
+      (`E_MCP_REMOTE_NOT_SUPPORTED` for any other bind).
+- [ ] Transport bounds active: header/request/keepalive timeouts, 4 MiB body cap,
+      POST-only, in-flight ceiling (503 `E_MCP_HTTP_BUSY`).
+- [ ] Tool/resource catalogs are deterministic and identical across transports.
+- [ ] Task-aware mutation tools require explicit `taskId`.
+- [ ] Capability gates re-checked per invocation; tool input cannot elevate policy.
+- [ ] `task-recover`, legacy repair, and force unlock are separately gated;
+      legacy repair hidden by default; `operatorAuthorized` absent from schemas.
+- [ ] No generic shell/exec tool exists.
+
+## Ownership/recovery parity
+
+- [ ] `task/ownership` derives exclusively from the canonical claim resolver.
+- [ ] Forged COMPLETE stays INCONSISTENT with retained claims on every surface.
+- [ ] RECOVERED tasks block ordinary mutation; `task-resume` reacquires canonically.
+- [ ] Concurrent resume yields exactly one winner.
+
+## Safety
+
+- [ ] `maxExecutionTimeMs` enforced: missing→max, zero/negative/float rejected,
+      over-max rejected.
+- [ ] Error payloads preserve canonical codes; secrets redacted; stacks stripped;
+      messages bounded.
+- [ ] Oversized tool/resource output refused with `E_MCP_RESULT_TOO_LARGE`.
+
+## Packaging/docs
+
+- [ ] Core tarball contains integration modules and both integration docs.
+- [ ] MCP tarball contains both bins, src, README; core tarball never ships
+      `integrations/`.
+- [ ] Server `serverInfo.version` equals MCP package.json version.
+- [ ] MCP README documents stdio-default + optional loopback-only HTTP.
+- [ ] THIRD_PARTY_NOTICES covers the Model Context Protocol SDK.
+- [ ] CHANGELOG entries present.
+
+## Exact output-bound gates (post-PR #80)
+
+- [ ] Output bounds measure the exact UTF-8 serialization transmitted
+      (pretty-printed included), not compact JSON.
+- [ ] Compact-below/pretty-above regression covered by tests.
+- [ ] UTF-8 byte-count regression covered by tests.
+- [ ] `forgeloop_capabilities` complete result is bounded like command tools.
+- [ ] Non-size serialization errors are rethrown, not mislabeled as overflow.
+- [ ] Structured tool input is byte-bounded (`E_MCP_INPUT_TOO_LARGE`).
+
+## Documentation gates
+
+- [ ] Repository-wide documentation audit complete.
+- [ ] Documentation manifest/index current.
+- [ ] Generated references current (`docs:generate` leaves no diff).
+- [ ] README / CHANGELOG current.
+- [ ] MCP / Universal Integration docs current.
+- [ ] Security docs current.
+
+## Publication boundary
+
+- [ ] Release identity verification passes.
+- [ ] Publication of either package is separately authorized; this checklist
+      does not itself authorize npm publishing.

package/docs/TROUBLESHOOTING.md

@@ -24,6 +24,7 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Baseline re-record blocked during active task (`E_BASELINE_RECORD_DURING_ACTIVE_TASK`)](#symptom-baseline-re-record-blocked-during-active-task)
 - [Mutation checker execution error (`E_CHECK_MUTATION_EXECUTION_ERROR`)](#symptom-mutation-checker-execution-error)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
+- [Task claim conflict or recovered task](#symptom-task-creation-blocked-by-a-write-claim-conflict-e_task_scope_conflict)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
 
 ---
@@ -235,6 +236,14 @@ forgeloop complete --task <id>
 ```
 
 Write claims release only when completion is validator-backed (`COMPLETE`).
+A `phase: COMPLETE` that was never produced by the official completion pipeline
+is not sufficient: the ownership resolver requires canonical lifecycle proof (a
+validated ledger containing the task-bound `COMPLETION_VALIDATED` event with
+coherent state). Unproven completion reports
+`E_COMPLETION_OWNERSHIP_UNPROVEN` / `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`,
+retains historical claims, and blocks mutation and overlapping acquisition.
+Re-run the official completion pipeline or restore the canonical completion
+event; never edit `work-state.json` by hand.
 
 ---
 
@@ -303,6 +312,94 @@ export FORGELOOP_TASK="<task-id>"
 
 ---
 
+### Symptom: Task Creation Blocked by a Write-Claim Conflict (`E_TASK_SCOPE_CONFLICT`)
+
+#### What it means
+
+Another non-`COMPLETE` task already holds a write claim that overlaps the claims you requested. ForgeLoop inspects the conflicting task automatically before failing and attaches a deterministic classification to the error.
+
+#### Inspect
+
+The conflict error carries machine-readable fields directly on each
+`error.conflicts[]` entry, plus the full nested `inspection`:
+
+- `classification`: one of `ACTIVE`, `RECOVERABLE`, `STALE`, `ABANDONED`, `INCONSISTENT`, `RECOVERED`, or `COMPLETE`;
+- `reasonCodes`: the deterministic evidence codes behind the classification;
+- `nextAction`: the deterministic recovery or wait action;
+- `commandSpecs`: direct-process command metadata and required inputs;
+- `inspection`: the complete classification evidence.
+
+Classification is derived from machine state only: the validated relationship
+between descriptor, work state, recovery artifact, and complete recovery
+history; lock/lease,
+checkpoint freshness, drift kinds, ledger validity, all recorded check statuses,
+verification evidence, meaningful ledger activity, and idle time. Lock state
+distinguishes `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; unknown,
+corrupt, or unreadable evidence fails closed as `INCONSISTENT`. A `REVIEWING`
+phase plus an old timestamp alone is never `STALE`; post-execution tasks whose
+only drift is `REPOSITORY_CHANGED` remain `RECOVERABLE`.
+
+#### Safe recovery
+
+Follow the classification:
+
+```bash
+# RECOVERABLE: reconcile through the official pipeline first
+forgeloop reconcile-closure --task <task-id> --id <verification-id> \
+  --requirement "<exact contract verification text>" -- <command>
+
+# STALE / ABANDONED only: caller-acknowledged claim release
+forgeloop task-recover --task <task-id> --acknowledge-recovery --json
+
+# RECOVERED: reacquire claims through normal ownership checks
+forgeloop task-resume --task <task-id> --json
+
+# INCONSISTENT: diagnose; do not force claim release
+forgeloop validate-protocol --task <task-id> --json
+```
+
+`task-recover` uses an explicit allowlist: only `STALE` and `ABANDONED` are
+accepted. It refuses `ACTIVE`, `RECOVERABLE`, `INCONSISTENT`, `RECOVERED`,
+`COMPLETE`, and unknown future classifications. A stale task lock is released
+only if its lock ID, heartbeat, and owner instance still match the observation;
+recovery then revalidates phase, revision, ledger sequence, and classification
+under project-claims and task locks.
+
+The command writes durable `recovery.json` and a linked append-only recovery
+event in one transaction. For PR #66 compatibility, the writer retains the
+event name `OPERATOR_RECOVERY_RECORDED`, but records
+`authorityKind: CALLER_ACKNOWLEDGED`; readers also accept
+`TASK_RECOVERY_RECORDED`. Recovery does not refresh `work-state.json`, change
+phase, erase evidence, alter policy/continuity, or fabricate completion.
+Historical descriptor claims remain visible, while canonical effective claims
+are empty only when that relationship validates; ordinary mutations then fail
+with `E_TASK_RECOVERED`. Fake, missing, corrupt, deleted, or mismatched recovery
+evidence is `INCONSISTENT`, keeps historical claims effective, disables
+mutation, and routes `next` to `RESOLVE_RECOVERY_INCONSISTENCY`.
+
+`--acknowledge-recovery` is a caller declaration, not host-attested authority.
+The deprecated `--operator-authorized` alias has the same limited meaning.
+Only `task-resume` can transactionally remove recovery state and reacquire
+claims. If another task owns an overlapping path, resume returns
+`E_TASK_SCOPE_CONFLICT` and leaves the recovered task suspended.
+
+Never create, delete, or edit `recovery.json` manually. Never remove task
+recovery state to resume a task. Never interpret `recovery.json` without
+validating its ledger binding. Direct changes bypass locks, transactions,
+expected revisions, and the append-only ledger.
+
+If `.forgeloop/.claims.lock` is stale, ForgeLoop quarantines and removes it only
+when `lockId`, `heartbeatAt`, and `ownerInstanceId` still match. A live lock
+returns `E_TASK_LOCKED`; unknown, corrupt, or concurrently replaced ownership
+returns `E_PROJECT_CLAIMS_LOCK_INCONSISTENT`. Do not force-delete unknown lock
+ownership.
+
+A project containing active task recovery state requires ForgeLoop 1.4.0 or
+newer. An older reader that cannot advertise validated claim projection must
+fail closed instead of inferring ownership from the descriptor or tombstone.
+
+---
+
 ### Symptom: Verification Tool is Missing
 
 #### Error Code: `E_VERIFICATION_TOOL_UNAVAILABLE`
@@ -584,6 +681,7 @@ forgeloop next --task <id> --json
 | `E_CHECK_STATUS_CONTRADICTION` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_CIRCULAR_COMPLETION_REQUIREMENT` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_COMMAND_RESOLUTION_AMBIGUOUS` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_COMPLETION_OWNERSHIP_UNPROVEN` | Work-state claims COMPLETE but the canonical lifecycle/ledger completion proof is missing or invalid, so historical claims stay reserved. | Restore the canonical completion event and a valid ledger, or re-run the official completion pipeline; phase=COMPLETE alone never releases claims. |
 | `E_COMPLETION_RECOVERY_UNAUTHORIZED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_COMPLETION_REJECTED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_COMPLETION_REJECTION_LEDGER_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -622,6 +720,7 @@ forgeloop next --task <id> --json
 | `E_GATE_UNVERIFIED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_INIT_KIT_CONFLICT` | A canonical ForgeLoop kit destination already exists with content that does not match the shipped canonical template. | Inspect the conflicting `.forgeloop/kit/...` file. If it is stale or partial ForgeLoop output, remove or restore it and rerun `forgeloop init`. Do not overwrite unknown content automatically. |
 | `E_INSTALLATION_AUTHORITY_REQUIRED` | Attempted software installation without host authority grant. | Use local non-installing binaries or request host authority grant. |
+| `E_LEGACY_RECOVERY_MIGRATION_INVALID` | The legacy recovery-event repair was refused because the ledger does not match the exact known legacy defect signature, has incompatible later activity, holds a live lock, or is otherwise ambiguous. | Inspect the structured plan/errors; ambiguous or tampered ledgers stay INCONSISTENT and are never migrated. |
 | `E_MIGRATION_INCOMPLETE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_MIGRATION_WRITE_VERIFY` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_MIXED_TERMINAL_REQUIREMENT` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -654,6 +753,7 @@ forgeloop next --task <id> --json
 | `E_PROFILE_SOURCE_UNKNOWN` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PROFILE_UNVERIFIED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PROGRESS_STALLED` | Persisted correction history shows no new diagnostic information. | Use an independent check, revisit assumptions, or record a materially different diagnosis. |
+| `E_PROJECT_CLAIMS_LOCK_INCONSISTENT` | The project-wide claim reservation lock has unknown, corrupt, or concurrently changed ownership metadata. | Inspect .forgeloop/.claims.lock and retry only after its lease and owner identity can be validated; never force-delete unknown ownership. |
 | `E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PUBLICATION_CLAIM_UNVERIFIED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PUBLICATION_REQUIREMENT_PENDING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -683,9 +783,12 @@ forgeloop next --task <id> --json
 | `E_STATE_REVALIDATION_REQUIRED` | The work-state checkpoint must be revalidated before the lifecycle can continue. | Run forgeloop reconcile-closure for externally satisfied EXECUTING tasks, or inspect the freshness reasons for other drift. |
 | `E_STATE_TASK_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_ALREADY_EXISTS` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_TASK_ALREADY_RECOVERED` | The task already has active durable recovered state. | Inspect the existing recovery metadata; use task-resume to reacquire claims or leave the task recovered. |
 | `E_TASK_AMBIGUOUS` | Multiple tasks exist in the project but no task selector was provided. | Select a task explicitly using --task <id> or FORGELOOP_TASK=<id>. |
 | `E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_CHANGE_OUTSIDE_SCOPE` | Modified paths in repository exceed the declared task write claims. | Update write claims with forgeloop task-scope or revert out-of-scope modifications. |
+| `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT` | ForgeLoop cannot prove whether a task still owns its historical write claims. | Repair and validate the task descriptor, recovery artifact, and complete event ledger before acquiring overlapping claims or mutating the task. |
+| `E_TASK_COMPLETE` | A validator-backed COMPLETE task is terminal and cannot be mutated. | Create or select a non-terminal task for further work; do not modify terminal task state. |
 | `E_TASK_CONTEXT_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_DESCRIPTOR_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_KEY_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -695,8 +798,15 @@ forgeloop next --task <id> --json
 | `E_TASK_MIGRATION_IDENTITY_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_MIGRATION_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_NOT_FOUND` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_TASK_NOT_RECOVERED` | task-resume was requested for a task without active recovered state. | Inspect the task with forgeloop task-show; task-resume is only valid while recovery.json is active. |
+| `E_TASK_RECOVERED` | The task released its write claims through recovery and ordinary mutation is suspended. | Run forgeloop task-resume --task <id> to reacquire the released claims before mutating the task. |
+| `E_TASK_RECOVERY_AUTHORITY_INVALID` | Recovery authority metadata is invalid or claims host attestation without a host-owned grant reference. | Use caller acknowledgement, or provide a host-attested recovery grant through a trusted host integration. |
+| `E_TASK_RECOVERY_AUTHORIZATION_REQUIRED` | task-recover requires explicit caller acknowledgement; this is not host-attested authority. | Re-run with --acknowledge-recovery only when evidence shows the task is STALE or ABANDONED; --operator-authorized remains a deprecated alias. |
+| `E_TASK_RECOVERY_INCONSISTENT` | Claim-release recovery was refused because the task state, recovery artifact, lock, or event ledger is inconsistent. | Repair the underlying artifact through its dedicated recovery surface; do not force-complete an unreadable task. |
+| `E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE` | Claim-release recovery was refused because canonical lifecycle reconciliation is available. | Use forgeloop reconcile-closure and the normal verification/completion pipeline instead of task-recover. |
+| `E_TASK_RECOVERY_UNSAFE` | Claim-release recovery was refused because the conflicting task is active, inconsistent, already complete, or holds a live lease. | Resolve the reported classification first; live leases must expire or be released by their owner before recovery. |
 | `E_TASK_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
-| `E_TASK_SCOPE_CONFLICT` | Task write claims overlap with another non-complete task in the same checkout. | Adjust write claims to non-overlapping paths or run tasks in separate worktrees. |
+| `E_TASK_SCOPE_CONFLICT` | Task write claims overlap with another non-complete task in the same checkout. | Inspect the conflicting task classification reported in error.conflicts, then reconcile or recover it through its reported official recovery commands before retrying task creation. |
 | `E_TASK_SCOPE_DIRTY` | Claimed paths contain pre-existing uncommitted changes. | Commit or stash changes in claimed paths before defining or adopting the scope. |
 | `E_TASK_SCOPE_FROZEN` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_TASK_SCOPE_REQUIRED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |

package/docs/UNIVERSAL_INTEGRATION.md

@@ -0,0 +1,48 @@
+# Universal ForgeLoop Integration
+
+ForgeLoop applies to any agent, harness, IDE, or orchestration runtime — with
+or without MCP. The universal rule:
+
+> If the active host exposes an official ForgeLoop structured integration,
+> prefer it for protocol operations. Otherwise use the project-local ForgeLoop
+> CLI. Never manually synthesize ForgeLoop-managed lifecycle, claim, recovery,
+> ledger, or completion state because an integration is unavailable.
+
+## The programmatic integration API
+
+`@cassiomc1/forgeloop/integration` (integration API version 1) is the
+transport-neutral entrypoint:
+
+```js
+import {
+  executeForgeLoopCommand,
+  validateForgeLoopCommandInput,
+  getForgeLoopCapabilities,
+  classifyForgeLoopInvocation,
+  readForgeLoopIntegrationResource,
+} from "@cassiomc1/forgeloop/integration";
+```
+
+- `executeForgeLoopCommand({command, projectPath, input})` returns a
+  deterministic envelope: `{ok, command, exitCode, result, error, metadata}`.
+  Domain rejections (preflight BLOCKED, audit INVALID) keep `ok:true` with a
+  non-zero exit code; `ok:false` means the command could not be executed and
+  preserves the canonical public error code.
+- Ownership values always come from `resolveTaskClaimState()` through the
+  `task/ownership` resource — never derived from raw artifacts.
+- Invocation risk classes (READ_ONLY, LOOP_MUTATION, CLAIM_REACQUISITION,
+  EXTERNAL_EXECUTION, MAINTENANCE, CLAIM_RELEASE_RECOVERY, LEGACY_MIGRATION,
+  FORCE_DESTRUCTIVE) describe what an invocation would do; launch policy
+  decides what is allowed.
+
+## Consumers
+
+| Surface | Entry |
+| --- | --- |
+| ForgeLoop CLI | human terminal rendering over the same executors |
+| ForgeLoop MCP | `@cassiomc1/forgeloop-mcp`: stdio (default/recommended) plus optional strict-modern loopback-only HTTP; see [MCP.md](./MCP.md) |
+| Studio / IDE / CI adapters | the same integration subpath |
+
+All consumers share one protocol authority: `.forgeloop/` state written only
+by canonical ForgeLoop commands, so cross-harness continuity and recovery work
+identically regardless of transport.