@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/docs/EXECUTION_TRACE.md

@@ -0,0 +1,76 @@
+# ForgeLoop Execution Trace
+
+Reference for `history`, `trace`, `reflect`, and task-level `inspect` observability projections (ForgeLoop 1.6.0+).
+
+All views are deterministic read-only projections of canonical artifacts (event ledger + work state). There is no second truth store.
+
+## history
+
+```bash
+forgeloop history --task <id> [--json] [--compact] [--verbose]
+                  [--type <types>] [--phase <phases>] [--failures] [--checks]
+                  [--since <ts>] [--until <ts>] [--limit <n>]
+```
+
+Human output shows chronological events with timestamps from the ledger. JSON output includes:
+
+- `snapshot`: consistency anchors (`stateRevision`, `ledgerTailSequence`)
+- `summary`: event/check/diagnostic counts
+- `historyQuality`: `COMPLETE | PARTIAL | MINIMAL` with reasons
+- `integrity`: ledger validation result
+- `events`: normalized events (category, phase, provenance, references)
+
+Filters are presentation-only; they never weaken integrity validation. Truncation via `--limit` is explicit (`truncated: true`).
+
+## trace
+
+```bash
+forgeloop trace --task <id> --json
+```
+
+Machine-readable reconstruction containing events, lifecycle transitions (including `VERIFICATION_STARTED`), check attempts, diagnostics (legacy diagnoses, structured cases, interventions, dispositions), failure signatures/surfaces, executions, evidence, continuity, recovery, completion, integrity, and snapshot anchors.
+
+Failure surfaces include every canonically verified cycle; a successful
+verification appears explicitly as `surface: []`, enabling deterministic
+`REDUCED -> empty` and intervention `IMPROVED` classification.
+
+Attempt cardinality comes primarily from ledger chronology: one ledger attempt plus its state checkpoint counts once; two distinct ledger events count twice; a state-only check appears as one fallback attempt (`source: "state-fallback"`). Phases are reconstructed forward from milestone events (`TASK_RECEIVED -> RECEIVED` ... `COMPLETION_VALIDATED -> COMPLETE`); events between milestones carry derived phases (for example failed verification -> `DIAGNOSING`, recorded intervention -> `CORRECTING`) with `phaseQuality: "authoritative" | "derived" | "unknown"`. Determinism: identical canonical artifacts produce identical traces except `snapshot.capturedAt`.
+
+## reflect
+
+```bash
+forgeloop reflect --task <id> [--json]
+```
+
+Whole-task retrospective (gain truth comes from the canonical cycle analysis;
+`stallAnalysis` explains historical repetition without changing the fail-fast
+stall decision): verification cycles, failure surfaces, hypothesis summary, intervention effectiveness (`PENDING | INFORMATIVE | NON_INFORMATIVE | IMPROVED | REGRESSED`), strategy fingerprints, oscillation patterns, signals, and a recommended protocol action. Deterministic — ForgeLoop does not call an LLM.
+
+## inspect --task
+
+`forgeloop inspect --task <id>` extends target health with an additive `taskInspection` section: snapshot, lifecycle transitions, history quality, verification attempts per requirement, diagnostic summary, progress evaluation, integrity issues, deterministic explanation reason codes, and the safe next command. Existing top-level inspect fields are unchanged.
+
+## Read-only invariant
+
+`history`, `trace`, `reflect`, `inspect`, `progress` never mutate protocol state, acquire ownership, or append events. Test suites enforce this by hashing the complete `.forgeloop` tree before/after invocation.
+
+## Durable actions in the trace
+
+`trace --json` adds an `actions` projection with totals, state and capability
+counts, required/verified/failed/ambiguous counts, repeated idempotency-key
+attempts, reconciliation count, and action-event count. The projection reads
+the task action artifacts and the same ledger already used by history; it is
+not a second source of lifecycle truth.
+
+An action recorded as `COMMIT_UNKNOWN` is an external-state uncertainty, not a
+diagnostic failure. Reflection surfaces `EXTERNAL_ACTION_RECONCILIATION_REQUIRED`
+and recommends `RECONCILE_EXTERNAL_ACTION` before ordinary retry guidance.
+`FORGELOOP_EXECUTED`, `HOST_REPORTED`, and `EXTERNAL_OBSERVED` remain distinct
+provenance values.
+
+`forgeloop metrics --task <id> --json` projects trajectory counts, action
+outcomes, observed executions, and first/last authoritative ledger timestamps.
+Usage fields remain `null` with `source: "UNKNOWN"` when the host did not
+report them. `forgeloop eval --task <id> --scenario <path> --json` evaluates a
+validated current trace against a project-local reference scenario; an
+efficiency ratio is omitted when no positive comparable-step reference exists.

package/docs/MCP.md

@@ -46,6 +46,39 @@ Capability flags (process-scoped, immutable after launch):
 - `forgeloop://task/{taskId}/ownership` — canonical validated ownership
 - `forgeloop://task/{taskId}/contract`
 - `forgeloop://task/{taskId}/continuity`
+- `forgeloop://task/{taskId}/actions`
+- `forgeloop://task/{taskId}/action/{actionId}`
+- `forgeloop://task/{taskId}/approvals`
+- `forgeloop://task/{taskId}/metrics`
+- `forgeloop://task/{taskId}/evaluations`
+- `forgeloop://project/capability-policy`
+
+The durable-action resources are read-only projections. The first release does
+not expose `run-action` or host-attestation minting over MCP. An action that is
+`COMMIT_UNKNOWN` is surfaced as an external reconciliation requirement; MCP
+transport/session metadata cannot authorize a retry or manufacture
+`HOST_ATTESTED` authority. Capability policy remains policy, not authority.
+
+### Approval resolution and reconciliation settlement capabilities
+
+Two launch flags expose transport surfaces; neither creates host authority:
+
+- `--allow-approval-resolution` exposes the `approval-resolve` tool.
+  Resolving an approval as `HOST_ATTESTED` still requires a trusted
+  out-of-band authority context supplied by the embedding host through
+  `createForgeLoopMcpServer({ authorityContextProvider })`. Without a
+  provider, `HOST_ATTESTED` resolutions fail closed with
+  `E_ACTION_AUTHORITY_REQUIRED`. Tool arguments can never carry the context:
+  any actor-supplied `authorityContext` property is stripped before dispatch.
+- `--allow-reconciliation-settlement` exposes settlement-class
+  `action-reconcile` invocations (`--outcome COMMITTED|NOT_COMMITTED`).
+  Recording an `UNKNOWN` observation needs no special capability, but settling
+  external commit state is independently gated and still requires trusted
+  host attestation plus evidence at the core layer.
+
+Capability introspection reports whether these surfaces are enabled
+(`hostAttestationAvailable: false` by default) but never exposes grant
+content.
 
 Raw recovery artifacts, transaction journals, lock files, and unbounded event
 ledgers are intentionally not exposed.

package/docs/RECIPES.md

@@ -21,6 +21,7 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 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)
+16. [Execute a Durable External Action Safely](#recipe-16--execute-a-durable-external-action-safely)
 
 ---
 
@@ -346,6 +347,72 @@ artifact against the complete ledger history. If `next` returns
 `RESOLVE_RECOVERY_INCONSISTENCY`, run `validate-protocol`; do not create, edit,
 or delete `recovery.json` manually.
 
+---
+
+### Recipe 16 — Execute a Durable External Action Safely
+
+Record the intended external effect before execution, satisfy the capability
+policy and fingerprint-bound approval, and execute with an exact argument list:
+
+```bash
+forgeloop action-propose --task release --id action-publish --capability external.publish --effect-class EXTERNAL_PUBLICATION --target registry/release --operation "publish release" --idempotency-key release:publish:v1 --required-for-completion
+forgeloop approval-request --task release --approval approval-publish --action action-publish --reason "reviewed release"
+forgeloop approval-resolve --task release --approval approval-publish --decision APPROVED --authority CALLER_ACKNOWLEDGED
+forgeloop run-action --task release --action action-publish --capability external.publish --effect-class EXTERNAL_PUBLICATION --target registry/release --idempotency-key release:publish:v1 --required-for-completion -- npm publish
+# If the external outcome cannot be proven after start, do not retry:
+forgeloop action-reconcile --task release --action action-publish --outcome UNKNOWN
+```
+
+Provenance and authority truths for this recipe:
+
+- `CALLER_ACKNOWLEDGED` approval resolution records an acknowledgement; if the
+  capability policy requires `REQUIRE_APPROVAL`, only a fresh `HOST_ATTESTED`
+  approval resolved through a trusted embedding-host boundary authorizes the
+  action. The standalone CLI can never mint it.
+- `forgeloop next` evaluates the current capability policy before inspecting
+  approval state, but only after validating that the capability artifact is
+  bound to the active policy lock and task snapshot. Historical or stale
+  approvals never override `ALLOW`, `DENY`, or `REQUIRE_AUTHORITY`; only a
+  currently applicable `REQUIRE_APPROVAL` decision can make a pending approval
+  the active resolver target.
+- `commands` in next-action guidance are safe standalone CLI commands. A
+  host-only authorization is returned with `commands: []` and structured
+  `hostActionRequired`/`authorityRequired` data so an embedding host can invoke
+  `action-authorize` while preserving its trusted authority context.
+- `approval-request` is policy-aware: it creates a pending approval only for
+  `REQUIRE_APPROVAL`; `ALLOW`, `DENY`, and `REQUIRE_AUTHORITY` reject the request
+  without creating an approval artifact. A changed `capabilities.json` alone is
+  not a valid policy update: restore the recorded epoch or refresh the lock and
+  task snapshot through the supported policy lifecycle first.
+- `COMMIT_UNKNOWN` is an explicit reconciliation boundary, not a failed retry.
+  Recording `UNKNOWN` keeps the action ambiguous. Settling `COMMITTED` or
+  `NOT_COMMITTED` requires trusted host attestation plus evidence through a
+  trusted integration boundary. A trusted `NOT_COMMITTED` returns the action
+  to `PROPOSED` so authorization is re-evaluated before any retry.
+
+After commit ambiguity is settled as `COMMITTED`, verify the independent
+postcondition before completion:
+
+```bash
+forgeloop run-check --task release --id check-release-live --requirement publication -- node scripts/check-release-live.js
+forgeloop action-verify --task release --action action-publish --evidence <execution-ref>
+```
+
+`COMMITTED != VERIFIED`: exit code 0 from the action command proves local
+completion only. Verification requires canonical evidence from an independent
+check execution.
+
+Inspect the observed trajectory without inventing usage data:
+
+```bash
+forgeloop metrics --task release --json
+forgeloop eval --task release --scenario scenarios/release.json --json
+```
+
+The efficiency comparison is present only when the scenario declares a
+positive `reference.comparableSteps`; absent host token/cost/model data stays
+unknown.
+
 ## Run ForgeLoop through MCP (safe mode)
 
 Start the local MCP adapter and inspect what it exposes:

package/docs/TROUBLESHOOTING.md

@@ -19,6 +19,7 @@ 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)
@@ -34,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
 ```
@@ -203,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`)
@@ -220,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.
@@ -235,6 +250,28 @@ 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
@@ -540,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`
@@ -669,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. |
@@ -698,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. |
@@ -705,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. |
@@ -713,13 +804,21 @@ 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. |
@@ -727,6 +826,7 @@ forgeloop next --task <id> --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. |
@@ -782,6 +882,7 @@ 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>. |
@@ -816,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 -->