@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/docs/TROUBLESHOOTING.md

@@ -19,11 +19,13 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [`forgeloop complete` returns `INCOMPLETE`](#symptom-forgeloop-complete-returns-incomplete)
 - [`forgeloop complete` returns `INVALID`](#symptom-forgeloop-complete-returns-invalid)
 - [Policy lock mismatch (`E_POLICY_LOCK_MISMATCH`)](#symptom-policy-lock-mismatch)
+- [Capability policy epoch drift (`E_ACTION_POLICY_DRIFT`)](#symptom-capability-policy-epoch-drift)
 - [Invalid policy artifacts fail closed (`E_POLICY_INVALID`)](#symptom-invalid-policy-artifacts-fail-closed)
 - [Policy weakening detected (`E_POLICY_WEAKENING`)](#symptom-policy-weakening-detected)
 - [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)
 
 ---
@@ -33,7 +35,7 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 Confirm the local CLI's public metadata before diagnosing a harness/version
 mismatch. This check does not create or mutate task state.
 
-<!-- FORGELOOP EXAMPLE: troubleshooting:protocol-info | exit=0 | json.errors.0.code=E_AUTHORITY_INVALID -->
+<!-- FORGELOOP EXAMPLE: troubleshooting:protocol-info | exit=0 | json.errors.0.code=E_ACTION_APPROVAL_NOT_REQUIRED -->
 ```bash
 forgeloop protocol-info --json
 ```
@@ -202,6 +204,20 @@ forgeloop status --task <id> --json
    forgeloop validate-protocol --task <id> --json
    ```
 
+If a checkpoint must be recreated after `clear-state` (or loss), `preflight`
+rebuilds a resumable checkpoint from the preserved contract and route artifacts.
+The resume phase is derived from the validated ledger chronology: a ledger that
+already records `EXECUTION_STARTED` (or a later verification milestone) resumes
+at the phase that chronology supports instead of restarting at `ROUTED`, so no
+duplicate non-repeatable lifecycle milestone is ever appended.
+
+A `PREFLIGHT_READY` that was superseded by a later `PREFLIGHT_BLOCKED` outcome
+(contract evolution, added gate requirement) does not block re-readiness: once
+the blocked preflight is resolved, `preflight` appends a fresh
+`PREFLIGHT_READY` bound to the current contract and route. A READY refresh whose
+details differ *without* an intervening BLOCKED outcome is still refused with
+`E_PHASE_CHRONOLOGY_INVALID`.
+
 ---
 
 ### Symptom: `EXECUTING`/`VERIFYING` task is stale because the repository moved (`E_REPOSITORY_CHANGED`)
@@ -219,7 +235,7 @@ forgeloop reconcile-closure --task <id> --id <verification-id> \
 
 `reconcile-closure` requires:
 
-1. The task is `EXECUTING` or `VERIFYING` (later phases are not reconcilable; work must return to a verification phase first).
+1. The task is `EXECUTING`, `VERIFYING`, or `REVIEWING`. A `REVIEWING` task additionally requires authorized completion recovery (a persisted evidence-only rejection bound to the current checkpoint), or a rejection snapshot that can be rebound (see below).
 2. The only drift is `REPOSITORY_CHANGED` (contract or required-artifact drift stays blocked).
 3. The append-only event ledger is valid.
 4. `--id` and `--requirement` exactly match a `VERIFICATION` item of the task contract, and the executed command exits 0, proving the objective is present in the current repository.
@@ -234,7 +250,37 @@ forgeloop advance --task <id> --to REVIEWING
 forgeloop complete --task <id>
 ```
 
+#### Drifted completion-rejection snapshots (`E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH`)
+
+A `REVIEWING` task with a persisted evidence-only completion rejection can lose
+its snapshot binding when the checkpoint is mutated after the rejection (for
+example by a recovery/resume cycle or a repository move). Both sanctioned
+closure paths — `reconcile-closure` from `REVIEWING` and the
+`REVIEWING -> VERIFYING` recovery transition — then fail with
+`E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH`, while `complete` cannot
+persist a fresh snapshot because it deduplicates logically identical rejections.
+This deadlocks the task.
+
+ForgeLoop resolves this with an append-only **rejection rebind**: when the only
+authorization failures are state/receipt fingerprint mismatches and the
+rejection's logical fields (`verificationCycle`, sorted `reasonCodes`, sorted
+`missingRequirementIds`) are still identical between work-state and the latest
+matching ledger rejection, the recovery surfaces automatically append a rebound
+`COMPLETION_REJECTED` event carrying the current fingerprints (referencing the
+snapshot it supersedes via `reboundFromStateFingerprint`) and re-bind the
+execution receipt. The original rejection is never modified, any logical
+difference is still refused, and closure must still produce fresh observed
+evidence in the current repository.
+
 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 +349,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`
@@ -443,6 +577,32 @@ forgeloop policy-status --json
 
 ---
 
+### Symptom: Capability Policy Epoch Drift
+
+#### Error Code: `E_ACTION_POLICY_DRIFT`
+
+#### What it means
+
+The current capability-policy artifact no longer matches the policy lock or
+the task-scoped policy snapshot. The same guard is enforced by
+`action-authorize`, `next`, and `approval-request`.
+
+#### Safe recovery
+
+ForgeLoop fails closed before authorization guidance or approval creation. Do
+not create an approval manually or retry `action-authorize` against the
+modified file. Restore the policy epoch recorded at task activation, or use
+the supported policy update flow to create a new lock and task snapshot, then
+rerun:
+
+```bash
+forgeloop next --task <id> --json
+```
+
+Changing `capabilities.json` alone is not a valid policy update.
+
+---
+
 ### Symptom: Invalid Policy Artifacts Fail Closed
 
 #### Error Code: `E_POLICY_INVALID`
@@ -572,6 +732,29 @@ forgeloop next --task <id> --json
 
 | Code | Meaning | Safe Resolution |
 | --- | --- | --- |
+| `E_ACTION_APPROVAL_NOT_REQUIRED` | The current capability policy allows the action without an approval artifact. | Do not create an approval; authorize the action through the current policy path. |
+| `E_ACTION_APPROVAL_REQUIRED` | Policy requires a current fingerprint-bound approval before this action may proceed. | Request approval with forgeloop approval-request and resolve it via forgeloop approval-resolve, then rerun the action. |
+| `E_ACTION_AUTHORITY_REQUIRED` | Policy requires host-attested authority that was not supplied through a host trust boundary. | Perform the action through a host integration that supplies trusted authority context; standalone CLI cannot mint it. |
+| `E_ACTION_AUTHORIZATION_INVALID` | Action authorization evidence is missing, incomplete, or was not produced by the canonical authorization service. | Authorize the action through forgeloop run-action or a trusted embedding host; caller surfaces can never mint AUTHORIZED. |
+| `E_ACTION_CAPABILITY_DENIED` | Capability policy denies this capability. | Obtain an operator policy change outside the task, or do not perform the action. |
+| `E_ACTION_CAPABILITY_UNKNOWN` | Action capability is not part of the canonical capability vocabulary. | Use a documented capability from forgeloop protocol-info; unknown capabilities fail closed. |
+| `E_ACTION_COMMIT_UNKNOWN` | External commit state of a started action cannot be proven. | Do not retry; reconcile the observed external state with forgeloop action-reconcile. |
+| `E_ACTION_EVIDENCE_INVALID` | Evidence supplied for verification or reconciliation is missing, malformed, or unbounded. | Supply bounded evidence references appropriate to the action type; do not paste raw external output into the ledger. |
+| `E_ACTION_IDEMPOTENCY_CONFLICT` | The idempotency key already binds to a different canonical action fingerprint in this task. | Use a new idempotency key with a new actionId, or reuse the existing logical action unchanged; never relabel an executed effect. |
+| `E_ACTION_IDEMPOTENCY_REQUIRED` | Side-effecting action class requires an idempotency key. | Supply a stable --idempotency-key that identifies the logical external action. |
+| `E_ACTION_INVALID` | Durable action artifact or parameters are malformed or schema-invalid. | Correct the action fields reported by the structured error, then retry through forgeloop action-propose or run-action. |
+| `E_ACTION_NOT_FOUND` | Referenced durable action ID does not exist for the task. | List actions with forgeloop action-show or propose the action first. |
+| `E_ACTION_POLICY_DRIFT` | The current capability policy does not match the policy lock or task policy snapshot binding this task. | Restore the policy epoch recorded at task activation or create a new valid lock and snapshot before side effects. |
+| `E_ACTION_POLICY_LOCK_REQUIRED` | A capability policy is present but no valid policy lock exists to bind authorization identity. | Record a valid policy lock (forgeloop baseline or policy-discover --write) before authorizing durable actions. |
+| `E_ACTION_RECONCILIATION_AUTHORITY_REQUIRED` | Settling COMMIT_UNKNOWN external state requires trusted host attestation that was not supplied out-of-band. | Reconcile through a trusted embedding host boundary; actor-supplied observations may only record UNKNOWN. |
+| `E_ACTION_RECONCILIATION_EVIDENCE_INVALID` | Settling reconciliation requires at least one bounded evidence reference binding the observation to the action. | Supply bounded external-state evidence references alongside trusted authority before settling ambiguity. |
+| `E_ACTION_RECONCILIATION_REQUIRED` | An action is COMMIT_UNKNOWN and blocks progress until explicitly reconciled. | Observe the external system and run forgeloop action-reconcile --outcome COMMITTED\|NOT_COMMITTED\|UNKNOWN with evidence references. |
+| `E_ACTION_STATE_MISMATCH` | Requested durable action transition is not part of the canonical state machine. | Inspect current action state with forgeloop action-show and use a legal transition; never edit action artifacts by hand. |
+| `E_ACTION_VERIFICATION_INVALID` | Verification evidence does not resolve to a canonical passed ForgeLoop artifact bound to this task and action. | Supply a canonical execution or check reference produced by run-check for this task; arbitrary strings fail closed. |
+| `E_ACTION_VERIFICATION_REQUIRED` | The action cannot reach VERIFIED through this surface; canonical independent postcondition evidence is required. | Run an independent verification check, then record it with forgeloop action-verify; exit code 0 alone is not verification. |
+| `E_APPROVAL_ALREADY_RESOLVED` | Approval is one-time resolvable and has already been approved or rejected. | Request a new approval if another decision is required. |
+| `E_APPROVAL_INVALID` | Approval artifact is malformed or does not bind the required fingerprint tuple. | Request a new approval with forgeloop approval-request; never hand-edit approval artifacts. |
+| `E_APPROVAL_STALE` | Approval no longer matches the current action fingerprint, contract fingerprint, task revision, or capability. | Request and resolve a fresh approval against the current action revision. |
 | `E_AUTHORITY_INVALID` | Authority grant file is malformed or expired. | Obtain a valid authority grant from host operator. |
 | `E_AUTHORITY_SCOPE_MISMATCH` | Authority grant does not cover the requested package. | Request updated authority scope. |
 | `E_AUTHORITY_UNTRUSTED_SOURCE` | Authority file placed inside untrusted project tree. | Place authority file in host-managed trusted location. |
@@ -584,6 +767,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. |
@@ -600,6 +784,8 @@ forgeloop next --task <id> --json
 | `E_CONTRACT_MISSING` | 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_CONTRACT_STALE` | Contract modified after downstream artifacts were generated. | Re-run forgeloop route and forgeloop preflight. |
 | `E_CONTRACT_UNRESOLVED_DECISION` | 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_CONTRIBUTOR_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_CONTRIBUTOR_REFERENCE_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_DECISION_CRITERION_INVALID` | Decision settlement criterion details or parameters are malformed. | Provide non-empty decision text and settledBy criterion. |
 | `E_DECISION_NOT_UNRESOLVED` | A settlement criterion referenced a decision not present in current unresolvedDecisions. | Use the exact current unresolved decision text or update the contract first. |
 | `E_DIAGNOSIS_CYCLE_MISMATCH` | Diagnosis verification cycle does not match the active work state verification cycle. | Record diagnosis for the current active verification cycle. |
@@ -607,6 +793,9 @@ forgeloop next --task <id> --json
 | `E_DIAGNOSIS_INVALID` | Diagnosis record details or parameters are malformed. | Provide valid failureClass, hypothesis, evidenceRefs, settledBy, and nextSafeAction. |
 | `E_DIAGNOSIS_NO_NEW_INFORMATION` | The proposed retry repeats the previous hypothesis with the same evidence. | Change the hypothesis, collect independent evidence, or change strategy. |
 | `E_DIAGNOSIS_REQUIRED` | Current correction cycle has no append-only diagnosis record. | Run forgeloop record-diagnosis with current failed evidence before correcting. |
+| `E_DIAGNOSTIC_CASE_CYCLE_MISMATCH` | Diagnostic case verification cycle does not match the active work state verification cycle. | Record the diagnostic case for the current active verification cycle. |
+| `E_DIAGNOSTIC_CASE_EVIDENCE_INVALID` | A diagnostic case evidence reference does not match any check from the active verification cycle. | Reference check IDs recorded during the active verification cycle. |
+| `E_DIAGNOSTIC_CASE_INVALID` | Structured diagnostic case details or parameters are malformed. | Provide valid observations, contributors, hypotheses with settlement criteria, and nextSafeAction. |
 | `E_EVIDENCE_COVERAGE_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_EVIDENCE_COVERAGE_PARTIAL` | 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_EVIDENCE_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. |
@@ -615,19 +804,29 @@ forgeloop next --task <id> --json
 | `E_EVIDENCE_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_EVIDENCE_STALE` | 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_EXECUTION_REF_INVALID` | Referenced execution ID does not exist. | Re-run check via forgeloop run-check. |
+| `E_FAILURE_SIGNATURE_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_FUTURE_LIFECYCLE_EVIDENCE` | 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_FUTURE_TERMINAL_EVIDENCE` | 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_GATE_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_GATE_STALE` | Referenced gate artifact changed after approval. | Update artifact SHA-256 in gate file. |
 | `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_HYPOTHESIS_DISPOSITION_EVIDENCE_INVALID` | Hypothesis disposition evidence references do not resolve to checks of the active cycle. | Reference at least one check ID recorded in the active verification cycle. |
+| `E_HYPOTHESIS_DISPOSITION_INVALID` | Hypothesis disposition is malformed or references an unknown hypothesis or disallowed transition. | Record a disposition for a known hypothesis using an allowed status transition. |
+| `E_HYPOTHESIS_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_HYPOTHESIS_SETTLEMENT_MISSING` | An open hypothesis lacks a falsifiable settlement condition. | Provide a structured settledBy predicate, check status, or observation binding. |
 | `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_INTERVENTION_HYPOTHESIS_MISSING` | Intervention does not bind to any hypothesis. | Bind the intervention to at least one recorded hypothesis. |
+| `E_INTERVENTION_INVALID` | Intervention record is malformed. | Provide id, kind, statement, and at least one bound hypothesisRef. |
+| `E_INTERVENTION_REFERENCE_INVALID` | Intervention references an unknown hypothesis. | Record the diagnostic case containing the hypothesis before recording the intervention. |
+| `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. |
 | `E_NATIVE_ADAPTER_STALE` | 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_NATIVE_ADAPTER_TARGET_MISSING` | 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_NEW_POLICY_VIOLATION` | New executable policy violation detected that is not present in brownfield baseline. | Fix the violation before completing the task. |
+| `E_OBSERVATION_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_PHASE_CHRONOLOGY_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_PHASE_PREREQUISITE_MISSING` | 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_PHASE_TRANSITION_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. |
@@ -654,6 +853,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. |
@@ -682,10 +882,14 @@ forgeloop next --task <id> --json
 | `E_STATE_MISSING_AFTER_PREFLIGHT_READY` | 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_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_STRATEGY_OSCILLATION` | Correction history oscillates between previously exhausted strategies without new information. | Gather a genuinely new observation or test a materially different falsifiable hypothesis. |
 | `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 +899,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. |
@@ -706,6 +917,9 @@ forgeloop next --task <id> --json
 | `E_TERMINAL_REQUIREMENT_TYPE_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_TERMINAL_REQUIREMENT_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_TERMINAL_STATUS_REGRESSION` | 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_TRACE_SNAPSHOT_INCONSISTENT` | Task artifacts changed while the execution trace was being read. | Rerun the read-only projection to obtain a consistent view. |
+| `E_TRAJECTORY_REFERENCE_REQUIRED` | Comparative efficiency requires a reference scenario with positive comparableSteps. | Provide --scenario with reference.comparableSteps, or omit efficiency from the result. |
+| `E_TRAJECTORY_SCENARIO_INVALID` | Trajectory scenario file is missing required fields or schema-invalid. | Correct the scenario JSON against schemas/trajectory-scenario.schema.json. |
 | `E_VERIFICATION_TOOL_UNAVAILABLE` | Required verification executable is missing in environment. | Use local equivalent, obtain host authority, or record NOT_VERIFIED. |
 
 <!-- END FORGELOOP GENERATED: public-error-codes -->

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.