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

@@ -18,9 +18,16 @@ integration and guide context. Use this map before editing documentation.
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational handoff and multi-tool resumption |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
+| Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
 | 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 |
+| Diagnostic model | [`docs/DIAGNOSTIC_MODEL.md`](./docs/DIAGNOSTIC_MODEL.md) | Structured diagnostic cases, interventions, hypothesis dispositions, information gain |
+| Execution trace and observability | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) | `history`, `trace`, `reflect`, and task-level `inspect` read-only projections |
+| 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 |
@@ -30,7 +37,8 @@ integration and guide context. Use this map before editing documentation.
 | Artifact and phase schemas | [`schemas/`](./schemas/) and [`CONTRACT_COVERAGE.md`](./CONTRACT_COVERAGE.md) | Versioned machine-readable contract |
 | CLI/package behavior | [`src/`](./src/) and [`tests/`](./tests/) | Executable implementation and regression evidence |
 | Guide content | [`ENG/`](./ENG/) | Context-specific, English-only operational guides |
-| Diagram | [`docs/forgeloop-flow.mmd`](./docs/forgeloop-flow.mmd) | Canonical Mermaid source; SVG is generated output |
+| Diagram governance | [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json) | Authoritative taxonomy, renderer mapping, canonical purposes, artifact ownership, and references |
+| Diagram maintainer entrypoint | [`docs/diagrams/README.md`](./docs/diagrams/README.md) | Typed Archify source, animated HTML explorer, animated SVG fallback, review, and regeneration workflow |
 
 ## Audience map
 
@@ -46,6 +54,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 +67,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)
@@ -81,25 +92,26 @@ process into adapters or README sections; link to the canonical source.
 ## Verification and release
 
 The Node regression suite, ESLint, c8, dependency policy, package boundary,
-and Mermaid render are the local executable checks. Python validators remain
+and Archify diagram render are the local executable checks. Python validators remain
 frozen CI-only compatibility tools because they cover historical Markdown,
 loop, and secret-scanning contracts that have not been migrated to Node. Their
 scope, exact commands, and migration boundary are recorded in
 [`scripts/CI_VALIDATORS.md`](./scripts/CI_VALIDATORS.md).
 
 The package has no runtime dependencies. Development dependencies are limited
-to ESLint, c8, and Mermaid CLI and are checked by
+to ESLint and c8 and are checked by
 `npm run dependency:policy`. GitHub Actions use `npm ci`, pinned action SHAs,
 CodeQL, dependency review, and generated-release notes; npm publication still
 uses trusted OIDC publishing and is not implied by local verification.
 
 ## Editing rules
 
-- Keep lifecycle prose, the Mermaid source, and the text-only README fallback
-  synchronized.
-- Keep generated `docs/assets/forgeloop-flow.svg` synchronized with the Mermaid
-  source by running `npm run docs:flow` and `npm run docs:check`. CI validates
-  the source fingerprint instead of comparing renderer-specific SVG geometry.
+- Keep lifecycle prose, the typed Archify source, generated outputs, and the
+  text-only README fallback synchronized.
+- Keep the generated HTML, SVG, and receipt synchronized with the Archify
+  source by running `npm run docs:diagrams` and `npm run docs:check`. CI
+  validates the renderer pin, source fingerprint, artifact hashes, and SVG
+  safety constraints.
 - Preserve the distinction between implemented behavior, local evidence, and
   external publication or production state.
 - Run `npm run lint`, `npm run coverage`, `npm run pack:check`, and the Python

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.
@@ -139,3 +179,23 @@ repository context and is always operational context rather than evidence.
 | Stale | Any | Changed | Run `forgeloop route` and `forgeloop preflight` to revalidate |
 | Invalid / Corrupted | Any | Any | Fail closed; inspect errors via `forgeloop doctor --json` |
 | Different Task ID | Present | Any | Do not merge contexts; clear or finish previous task first |
+
+## Durable actions are a separate external-state checkpoint
+
+Action artifacts under `actions/` describe side-effect intent and its canonical
+state; they do not replace `work-state.json`. Approval artifacts bind a single
+decision to the exact action fingerprint, contract fingerprint, task revision,
+and capability. Capability policy is configuration, not host authority.
+
+`FORGELOOP_EXECUTED` means ForgeLoop launched exact argv through `run-action`;
+`HOST_REPORTED` means an external host performed the operation; and
+`EXTERNAL_OBSERVED` means a later observation supplied reconciliation evidence.
+If the external outcome is uncertain, the action is `COMMIT_UNKNOWN`. It must
+not be retried or used to satisfy required completion until
+`forgeloop action-reconcile` records `COMMITTED`, `NOT_COMMITTED`, or
+`UNKNOWN`. ForgeLoop does not claim universal exactly-once execution.
+
+`metrics` and `eval` read the canonical trace, reflection, action artifacts, and
+ledger events. They never mutate lifecycle truth, invent usage/cost data, or
+create a second execution history; reference efficiency is emitted only when a
+project-local scenario provides comparable steps.

package/LOOP_ENGINEERING.md

@@ -27,6 +27,7 @@
 - [Precedence & Stop Conditions](#precedence)
 - [Final Delivery](#final-delivery)
 - [Cross-Harness Continuity](#cross-harness-execution-continuity)
+- [Durable Actions and Trajectory Evidence](#durable-actions-and-trajectory-evidence)
 - [Multi-Task Concurrent Project State](#multi-task-concurrent-project-state)
 
 ## Protocol applicability
@@ -1278,6 +1279,86 @@ completion. `CONTINUITY_CANNOT_GRANT_AUTHORITY`: continuity cannot authorize an
 installation or external action. <a id="FL-CONT-001"></a> **FL-CONT-001 — A receiving harness MUST reconcile**
 continuity against the current work state and checkout before acting on it.
 
+## Durable Actions and Trajectory Evidence
+
+Durable actions extend the existing task protocol; they do not turn ForgeLoop
+into an agent runtime, scheduler, queue, or workflow engine. Action intent,
+approval, execution provenance, reconciliation, and evaluation are task-local
+artifacts whose chronology remains in the same hash-chained `events.ndjson`.
+
+Every side-effecting action declares an explicit capability, effect class,
+bounded target, immutable idempotency key, and provenance. Project capability
+policy is a decision input (`ALLOW`, `DENY`, `REQUIRE_AUTHORITY`, or
+`REQUIRE_APPROVAL`); it is never host authority. `HOST_ATTESTED` authority can
+only cross the existing host trust boundary, and `run-action` accepts exact
+argv with no shell mode.
+
+### Durable action trust boundaries (hardened)
+
+The following invariants are enforced in core code and are regression-tested:
+
+- **Authorization is canonical.** No caller-controlled surface (`action-record`,
+  CLI flags, MCP tool arguments, project files, environment) can mint
+  `AUTHORIZED`. Only the core authorization service may transition
+  `PROPOSED -> AUTHORIZED` — through `run-action`, or explicitly through
+  `forgeloop action-authorize`, which is a pure adapter over the same service —
+  and only after the current capability policy, the persisted policy lock, and
+  the task policy snapshot agree. Every modern
+  `ACTION_AUTHORIZED` event binds the capability decision, capability-policy
+  fingerprint, policy-lock digest, task-policy digest, and — for
+  `REQUIRE_AUTHORITY`/`REQUIRE_APPROVAL` — the exact host authority or
+  fingerprint-bound approval. Post-authorization mutation of a bound approval
+  artifact is readiness/audit-visible.
+- **Verification is canonical, independent, and requirement-bound.**
+  `COMMITTED != VERIFIED`. A command exiting 0 proves only local completion.
+  `VERIFIED` is produced exclusively by `forgeloop action-verify` (or the
+  equivalent core service) against a passed ForgeLoop execution artifact that
+  is independent of the action's own commit execution and whose immutable
+  `requirement` exactly equals the action's requirement. New required actions
+  must declare a non-empty requirement at proposal time; historical required
+  artifacts without one remain readable but can never become trusted-satisfied.
+- **Reconciliation has exactly one replay truth.** A trusted `COMMITTED`
+  settlement emits `ACTION_RECONCILED(outcome=COMMITTED)` (the transition) plus
+  a same-revision informational mirror `ACTION_COMMIT_RECORDED(reconciled=true)`
+  (corroboration only). Ledger replay applies the transition exactly once and
+  validates mirror identity; forged or orphaned mirrors invalidate the ledger.
+- **Completion consumes readiness.** Required-action completion truth comes
+  from the canonical action-readiness projection, never from raw state labels.
+  A forged or legacy `VERIFIED` label without trusted authorization and
+  canonical verification evidence yields `UNTRUSTED` and blocks completion.
+- **Settling ambiguity requires trust.** Recording an `UNKNOWN`
+  reconciliation observation is always safe. Settling `COMMIT_UNKNOWN` as
+  `COMMITTED` or `NOT_COMMITTED` requires a trusted out-of-band host authority
+  context plus bounded evidence references bound to the event. Trusted
+  `NOT_COMMITTED` returns the action to `PROPOSED`, so any retry re-evaluates
+  policy, approval, authority, and the task policy snapshot; stale
+  authorization can never be reused.
+- **STARTED marks the launch boundary.** Deterministic pre-launch checks
+  (argv normalization, command resolution, installation authority, policy
+  identity, approvals) all run before `ACTION_STARTED`; post-start outcomes
+  remain conservative: spawn failure without launch is `FAILED`; anything
+  unproven is `COMMIT_UNKNOWN`.
+- **Capability policy participates in policy identity.** When
+  `.forgeloop/policy/capabilities.json` exists, its digest participates in the
+  policy lock, the active task policy snapshot, and authorization evidence.
+  Drift blocks before any side effect (`E_ACTION_POLICY_DRIFT`).
+- **Host context is out-of-band.** Trusted authority travels as an execution
+  context object supplied by an embedding host (`executeForgeLoopCommand` /
+  `createForgeLoopMcpServer({ authorityContextProvider })`). CLI flags such as
+  `--authority HOST_ATTESTED` are requested kinds, never proof. MCP launch
+  flags expose transport surfaces only; tool arguments can never carry
+  `authorityContext`.
+- **Guidance never lies about authority.** `forgeloop next` returns a
+  structured `authorityRequired` requirement for host-bound approvals instead
+  of recommending a command that cannot satisfy the blocker.
+
+Trajectory metrics and reference evaluations are read-only projections over the
+canonical trace, reflection, actions, and events. Missing tokens, costs,
+provider, model, or optimal-path data remain `null`/`UNKNOWN`; a comparative
+efficiency ratio exists only when a project-local reference scenario supplies
+`reference.comparableSteps`. Existing information-gain, intervention, failure
+signature, and oscillation diagnostics remain canonical.
+
 ## Multi-task concurrent project state
 
 ForgeLoop supports isolated, concurrent tasks within the same repository workspace.
@@ -1289,7 +1370,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 +1385,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.
@@ -421,3 +442,35 @@ machine and not a general memory subsystem. Work state owns lifecycle truth;
 the checkout owns implementation truth; checks/executions own verification
 truth; completion owns certification. Continuity only narrows what a receiving
 executor should inspect and continue.
+
+## Durable action and trajectory boundary
+
+Durable actions are protocol-owned task artifacts (`actions/`, `approvals/`,
+and `evaluations/`) projected through the existing hash-chained event ledger.
+They record intent, capability policy, approval binding, execution provenance,
+commit uncertainty, reconciliation, and verification without introducing a
+workflow runtime, scheduler, queue, or second ledger.
+
+The external side-effect boundary is deliberately conservative: exact argv is
+launched only through `run-action` with no shell mode; project capability
+policy cannot manufacture `HOST_ATTESTED` authority, and trusted host context
+travels out-of-band only (never inside command input, CLI flags, or tool
+arguments). Authorization and verification are canonical core services:
+callers cannot mint `AUTHORIZED` or `VERIFIED`, verification requires an
+independent passed ForgeLoop execution artifact, and required completion
+consumes the canonical action-readiness projection rather than raw state
+labels. Capability policy participates in policy identity: its digest is bound
+into the policy lock, the task policy snapshot, and authorization evidence, so
+drift blocks before any side effect. A started action whose external result is
+uncertain becomes `COMMIT_UNKNOWN`, which forbids retry until explicit
+reconciliation; settling ambiguity as `COMMITTED`/`NOT_COMMITTED` requires
+trusted host attestation plus evidence, and a trusted `NOT_COMMITTED` returns
+the action to `PROPOSED` so stale authorization can never be reused. This
+reduces duplicate-effect risk but cannot provide a universal exactly-once
+guarantee for arbitrary external systems.
+
+Metrics and trajectory evaluation are deterministic read-only projections of
+canonical trace/reflection evidence. They preserve unknown usage values and
+only compare efficiency when a project-local reference scenario exists. The
+existing diagnostic and reflection model remains the authority for information
+gain, intervention effectiveness, failure signatures, and oscillation.

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
@@ -261,6 +277,31 @@ configuration
 trust
 ```
 
+For durable actions, trusted host authority travels **out-of-band** through the
+programmatic integration API:
+
+```js
+await executeForgeLoopCommand({
+  command: "approval-resolve",
+  projectPath,
+  input: { /* actor-controlled command input only */ },
+  authorityContext: trustedHostContext, // host-supplied, never from input
+});
+```
+
+`authorityContext` and `runtimeContext` are separate executor parameters; they
+are never merged into `input`, never accepted as tool arguments, and cannot be
+minted by CLI flags, project files, environment variables, or transport
+sessions. MCP embeddings supply an immutable provider instead:
+
+```js
+createForgeLoopMcpServer({
+  projectPath,
+  allowApprovalResolution: true,      // transport surface only
+  authorityContextProvider: async ({ command }) => trustedContextOrNull,
+});
+```
+
 The host-attested source must still resolve outside the actor-writable target. A
 project-local authority reference may identify a grant, but it does not create
 the root of trust.
@@ -354,4 +395,50 @@ 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.
+
+## Durable actions and authority boundary
+
+Durable action support is additive to the integration contract. Read-only
+resources may expose action, approval, metrics, evaluation, and capability
+policy projections, but an integration must not treat transport metadata,
+session IDs, project policy, or actor prose as host authority. `HOST_ATTESTED`
+is accepted only from the existing host trust boundary.
+
+`run-action` is an exact-argv surface with no shell mode. Hosts that perform an
+operation themselves must record it as `HOST_REPORTED`; external observations
+used to settle uncertainty are `EXTERNAL_OBSERVED`. A started action whose
+external outcome cannot be proven is `COMMIT_UNKNOWN`: integrations must surface
+`E_ACTION_RECONCILIATION_REQUIRED` and must not retry automatically. The only
+forward path is explicit `action-reconcile` with bounded evidence.
+
+Trajectory metrics and evaluations are read-only projections over canonical
+events and trace/reflection data. Missing token/cost/model data remains unknown,
+and efficiency is comparable only when a project-local scenario supplies a
+positive reference step count. ForgeLoop remains an evidence protocol, not an
+agent runtime or workflow engine.

package/QUALITY_SCORECARD.md

@@ -31,6 +31,8 @@ policy are all present.
 | Contextual frontend taste | Taste is routed only to applicable premium frontend work, remains advisory, respects accessibility/performance/evidence, and has attribution without runtime dependency. |
 | Multi-agent coordination | Self-contained briefs, write/write and write/read ownership checks, dependency-set validation, reviewer independence, normalized results, and inline fallback. |
 | Security boundaries | Realpath containment, bounded untrusted JSON, threat model, nested secret scanning, publication evidence, and explicit authority rules. |
+| Durable external actions | Immutable action identity, idempotency conflict rejection, capability policy, fingerprint-bound approvals, exact-argv provenance, `COMMIT_UNKNOWN` reconciliation, completion blocking, and audit evidence. |
+| Trajectory evaluation | Read-only trace/reflection metrics, unknown usage preservation, canonical comparable-step definition, and scenario-bound efficiency without an arbitrary overall score. |
 | Maintenance quality | Small modules, built-in runtime, deterministic JSON contracts, malformed/version fixtures, package gates, and backward-compatible protocol versions. |
 
 ## Score rules