@cassiomc1/forgeloop 1.3.0 → 1.6.0

package/docs/CLI_REFERENCE.md

@@ -39,11 +39,12 @@ ForgeLoop uses a definition-driven command-line parser:
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
+| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
 | **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt) |
+| **Durable Actions & Approvals** | [`run-action`](#run-action), [`action-propose`](#action-propose), [`action-record`](#action-record), [`action-show`](#action-show), [`action-reconcile`](#action-reconcile), [`action-verify`](#action-verify), [`action-authorize`](#action-authorize), [`approval-request`](#approval-request), [`approval-resolve`](#approval-resolve) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
 
 <!-- END FORGELOOP GENERATED: cli-command-index -->
@@ -52,6 +53,163 @@ ForgeLoop uses a definition-driven command-line parser:
 
 ## 1. Setup & Maintenance
 
+## Durable Actions, Approvals, and Trajectory
+
+ForgeLoop is still a protocol/evidence layer, not an agent runtime. Use
+`COMMIT_UNKNOWN` as a hard stop: do not retry until an external observation is
+recorded with `action-reconcile`. `run-action` has no shell mode and executes
+only exact argv. Caller-reported and externally observed provenance are not host authority, and a project capability policy cannot mint host authority.
+
+### `run-action`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:run-action:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: stable durable action ID
+- `--capability <capability>`: canonical action capability
+- `--effect-class <class>`: durable action effect class
+- `--target <target>`: bounded external action target
+- `--idempotency-key <key>`: immutable logical action idempotency key
+- `--requirement <id>`: bound completion requirement
+- `--required-for-completion`: mark the action as required for completion
+- `--approval <id>`: current fingerprint-bound approval
+- `--timeout-ms <number>`: maximum command duration before termination
+- `-- <argv...>`: exact command argv; shell mode is never used
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:run-action:options -->
+
+### `action-propose`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-propose:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--id <id>`: stable action ID
+- `--capability <capability>`: canonical capability
+- `--effect-class <class>`: effect class
+- `--target <target>`: bounded action target
+- `--operation <text>`: bounded operation description
+- `--idempotency-key <key>`: logical action idempotency key
+- `--requirement <id>`: bound requirement
+- `--required-for-completion`: mark required for completion
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-propose:options -->
+
+### `action-record`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-record:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--state <state>`: next canonical action state
+- `--provenance <value>`: CALLER_REPORTED or EXTERNAL_OBSERVED
+- `--evidence-ref <ref>`: bounded external evidence reference
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-record:options -->
+
+### `action-show`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-show:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-show:options -->
+
+### `action-verify`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-verify:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--evidence <ref>`: canonical execution or check reference proving the postcondition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-verify:options -->
+
+### `action-authorize`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-authorize:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--approval <id>`: current fingerprint-bound approval
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-authorize:options -->
+
+### `action-reconcile`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-reconcile:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: ambiguous durable action ID
+- `--outcome <outcome>`: externally observed reconciliation outcome
+- `--evidence-ref <ref>`: bounded external evidence reference (repeatable)
+- `--observed-at <timestamp>`: external observation timestamp
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-reconcile:options -->
+
+### `metrics`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:metrics:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit trajectory metrics as JSON
+
+<!-- END FORGELOOP GENERATED: cli:metrics:options -->
+
+### `eval`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:eval:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--scenario <path>`: project-local trajectory scenario JSON
+- `--json`: emit evaluation as JSON
+
+<!-- END FORGELOOP GENERATED: cli:eval:options -->
+
+### `approval-request`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-request:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--approval <id>`: approval artifact ID
+- `--action <id>`: bound action ID
+- `--reason <text>`: bounded approval reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-request:options -->
+
+### `approval-resolve`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-resolve:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--approval <id>`: approval artifact ID
+- `--decision <decision>`: approval decision
+- `--authority <kind>`: CALLER_ACKNOWLEDGED or HOST_ATTESTED
+- `--host-grant-ref <ref>`: host boundary grant reference
+- `--reason <text>`: bounded resolution reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-resolve:options -->
+
 ### `protocol-info`
 
 Reports the public compatibility handshake required by external ForgeLoop harnesses.
@@ -496,6 +654,7 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
 
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: structured diagnostic case JSON file (mutually exclusive with legacy diagnosis fields)
 - `--hypothesis <text>`: specific root-cause hypothesis explaining the verification failure
 - `--failure-class <class>`: canonical failure class taxonomy
 - `--evidence-ref <check-id>`: reference to failed/blocked check from current cycle (repeatable)
@@ -516,6 +675,63 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
     --next-safe-action="Adjust offset +1 in slice.js"
   ```
 
+### `record-intervention`
+
+Records an append-only intervention bound to hypotheses; the described change is never executed by ForgeLoop.
+
+- **Purpose**: Records corrective or experimental changes (code, config, tests, instrumentation) associated with one or more hypotheses.
+- **When to use**: In `CORRECTING` phase after a structured diagnostic case has been recorded.
+- **Mutation**: Appends `INTERVENTION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-intervention:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: intervention JSON file describing the recorded change (never executed)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-intervention:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-intervention --task checkout --file intervention.json --json
+  ```
+
+### `record-hypothesis-disposition`
+
+Records an evidence-bound hypothesis disposition update in the lifecycle event ledger.
+
+- **Purpose**: Updates hypothesis status (SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED) based on recorded evidence.
+- **When to use**: After new verification evidence resolves an open hypothesis.
+- **Mutation**: Appends `HYPOTHESIS_DISPOSITION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-hypothesis-disposition:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--hypothesis <id>`: existing hypothesis ID to disposition
+- `--status <status>`: SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, or UNRESOLVED
+- `--evidence-ref <check-id>`: check ID supporting this disposition (repeatable)
+- `--reason <text>`: evidence-bound reason for the disposition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-hypothesis-disposition:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-hypothesis-disposition \
+    --task checkout \
+    --hypothesis h-timeout-latency \
+    --status SUPPORTED \
+    --evidence-ref checkout-tests \
+    --reason "Instrumented dependency time exceeded the timeout." \
+    --json
+  ```
+
 ### `validate-state`
 
 Validates `.forgeloop/task-state/<taskKey>/work-state.json` structure, hash chain, and repository binding.
@@ -821,7 +1037,7 @@ Displays human-readable or structured summary of current task state.
 
 ### `inspect`
 
-Inspects checkout changes and compares them against contract deliverables.
+Inspects checkout changes and compares them against contract deliverables. With `--task <id>`, human output renders a task inspection report (phase, cycle, ledger/snapshot health, progress, verification attempts, diagnostics, failure surface, signals, next command); `--json` keeps the full additive `taskInspection` section.
 
 - **Purpose**: Shows modified files, untracked files, and deliverable coverage.
 - **Mutation**: Read-only.
@@ -842,6 +1058,81 @@ Inspects checkout changes and compares them against contract deliverables.
   forgeloop inspect --json
   ```
 
+### `history`
+
+Shows chronological protocol history reconstructed from canonical ForgeLoop state.
+
+- **Purpose**: Answers "what happened during this task?" with deterministic, read-only reconstruction from the event ledger.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:history:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--type <list>`: comma-separated event types or categories to include
+- `--phase <list>`: comma-separated lifecycle phases to include
+- `--failures`: show only failed/blocked verification events
+- `--checks`: show only verification events
+- `--since <timestamp>`: include events at or after this timestamp
+- `--until <timestamp>`: include events at or before this timestamp
+- `--limit <number>`: show only the last N events after filtering
+- `--compact`: one line per event
+- `--verbose`: show full event data
+- `--json`: emit structured history output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:history:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop history --task auth-feature --json
+  ```
+
+### `trace`
+
+Emits detailed structured task trace with provenance and artifact relationships.
+
+- **Purpose**: Machine-readable protocol reconstruction consumed by history, reflect, task-level inspect, and external integrations.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:trace:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured trace output as JSON (default rendering is a summary)
+
+<!-- END FORGELOOP GENERATED: cli:trace:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop trace --task auth-feature --json
+  ```
+
+### `reflect`
+
+Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation.
+
+- **Purpose**: Whole-task retrospective that reports whether the run actually learned anything, without calling an LLM.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:reflect:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured reflection output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:reflect:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop reflect --task auth-feature --json
+  ```
+
 ### `policy`
 
 Evaluates compliance against a named policy pack.
@@ -1263,9 +1554,9 @@ protocol version.
 
 ### `task-unlock`
 
-Forces the release of a stale task lock.
+Forces the release of a task lock or CAS-safely releases an unchanged stale lease.
 
-- **Purpose**: Removes `.lock` file from the task directory when process crashed.
+- **Purpose**: Removes `.forgeloop/locks/<taskKey>.lock` when its owner is no longer valid. Prefer `--stale-only`; `--force` is an explicit unconditional maintenance action.
 - **Mutation**: Deletes task lock file.
 - **Options**:
 
@@ -1284,3 +1575,97 @@ Forces the release of a stale task lock.
   ```bash
   forgeloop task-unlock --task task-001 --force --json
   ```
+
+### `task-recover`
+
+Suspends mutation and releases effective claims for a task deterministically classified `STALE` or `ABANDONED`.
+
+- **Purpose**: For a task classified only `STALE` or `ABANDONED`, persists `recovery.json` plus a linked append-only event without changing work state or fabricating completion. The canonical claim-state resolver must validate both before claims become effective-empty. `RECOVERABLE` tasks must use `reconcile-closure`.
+- **Mutation**: Transactionally writes recovery state and appends the recovery event. Historical descriptor claims and all lifecycle evidence remain intact; ordinary mutations return `E_TASK_RECOVERED`.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-recover:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-recovery`: acknowledge release of claims for a STALE or ABANDONED task (required; not host attestation)
+- `--operator-authorized`: deprecated alias for --acknowledge-recovery; does not attest operator authority
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-recover:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-recover --task task-001 --acknowledge-recovery --json
+  ```
+
+`--acknowledge-recovery` is caller acknowledgement only. The deprecated
+`--operator-authorized` alias has the same semantics and is not host attestation.
+Fake, missing, corrupt, or mismatched recovery state is
+`E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`/`E_TASK_RECOVERY_INCONSISTENT`; historical
+claims remain reserved.
+
+### `task-resume`
+
+Reacquires a recovered task's write claims and restores ordinary mutation authority.
+
+- **Purpose**: Validates active recovery ownership, CAS-settles only an unchanged stale task lease, reuses normal claim-overlap and clean-checkout enforcement under project/task serialization, then removes `recovery.json` transactionally.
+- **Mutation**: Optionally updates historical claims in `task.json`, appends `TASK_RECOVERY_RESUMED`, and removes `recovery.json` in one transaction.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--claim <path>`: write claim to reacquire (defaults to all released claims) (repeatable)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-resume:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-resume --task task-001 --claim src --claim tests --json
+  ```
+
+With no `--claim`, the command attempts to reacquire all claims recorded in the
+active recovery artifact. It returns `E_TASK_SCOPE_CONFLICT` without removing
+recovery state when another active task owns an overlapping path.
+The resume event counts as meaningful task activity. Never create, edit, or
+delete `recovery.json` manually to emulate this command.
+
+### `task-repair-legacy-recovery`
+
+Migrates one recognized legacy recovery boundary event into the modern durable recovery representation.
+
+- **Purpose**: Proves that a historical `OPERATOR_RECOVERY_RECORDED` without `recoveryId` marks the effective task boundary and materializes its modern representation as an append-only `LEGACY_RECOVERY_MIGRATION_RECORDED` event plus a transactional `recovery.json`. The original legacy event is never modified.
+- **Mutation**: Appends the migration event at the ledger tail and writes `recovery.json` in one transaction under project claims locking.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-repair-legacy-recovery:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-recovery`: fresh explicit acknowledgement of the legacy boundary migration (required)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-repair-legacy-recovery:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-repair-legacy-recovery --task task-001 --acknowledge-recovery --json
+  ```
+
+Only the exact known legacy signature is eligible; ambiguous, tampered, or
+post-boundary-active ledgers fail closed with
+`E_LEGACY_RECOVERY_MIGRATION_INVALID` and ownership stays INCONSISTENT. A
+`STALE` task lease is settled only through CAS-safe stale release when the
+observed lock is unchanged; `LIVE` locks refuse with `E_TASK_LOCKED`, and
+`UNKNOWN`/`CORRUPT` locks fail closed with the lock preserved — never delete a
+lock file manually to unblock this command. The repair is idempotent: an
+already repaired task returns `{repaired: 0, alreadyRepaired: true}` only when
+the whole canonical recovery relationship validates; any mismatch fails closed.
+The repair itself never releases claims directly; ownership becomes validated
+recovery state and ordinary mutation remains blocked until `task-resume`.

package/docs/CROSS_HARNESS_CONTINUITY.md

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

package/docs/DIAGNOSTIC_MODEL.md

@@ -0,0 +1,181 @@
+# ForgeLoop Diagnostic Model
+
+Canonical reference for structured diagnostic cases, interventions, and hypothesis dispositions (ForgeLoop 1.6.0+, Protocol v1 additive).
+
+## Principles
+
+1. **Observation is not hypothesis.** Observations are bounded statements grounded in recorded evidence. Hypotheses are falsifiable claims that may explain observations.
+2. **Hypothesis is not proof.** Statuses are `OPEN`, `SUPPORTED`, `WEAKENED`, `FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`. ForgeLoop never emits `ROOT_CAUSE_CONFIRMED` or similar.
+3. **Append-only truth.** Diagnostic revisions are never rewritten; the ledger records evolving understanding.
+4. **Diagnostic prose is metadata.** Statements, settlement predicates, and next-safe-action text are never executed by ForgeLoop.
+
+## Structured diagnostic case
+
+One diagnostic revision for one verification cycle, recorded with:
+
+```bash
+forgeloop record-diagnosis --task <id> --file diagnostic-case.json --json
+```
+
+Legacy flag-based `record-diagnosis` syntax remains valid; both forms cannot be combined.
+
+Schema: `schemas/diagnostic-case.schema.json`. Bounded limits: 64 observations, 64 contributors, 32 hypotheses per case; statements up to 4096 characters; IDs match `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.
+
+### Semantic fingerprint
+
+`diagnosticFingerprint` hashes the canonicalized semantic content (cycle, failure class, observations/contributors/hypotheses semantics, next-safe action). Whitespace, key ordering, unordered reference arrays, and object IDs are excluded. Re-recording a semantically identical case is idempotent.
+
+### Revisions
+
+`diagnosticRevision` starts at 1 and increases monotonically per cycle. Each revision binds `previousDiagnosticFingerprint` to the prior active revision.
+
+## Interventions
+
+Recorded in `CORRECTING` phase:
+
+```bash
+forgeloop record-intervention --task <id> --file intervention.json --json
+```
+
+Interventions bind to at least one recorded hypothesis and carry a semantic fingerprint used to detect repetition without information gain.
+
+## Hypothesis dispositions
+
+```bash
+forgeloop record-hypothesis-disposition --task <id> \
+  --hypothesis h-timeout-latency --status SUPPORTED \
+  --evidence-ref checkout-tests --reason "..." --json
+```
+
+Allowed transitions: `OPEN → {SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED}`, `SUPPORTED → {WEAKENED, FALSIFIED, SUPERSEDED}`, `WEAKENED → {SUPPORTED, FALSIFIED, SUPERSEDED}`.
+
+## Diagnostic precedence
+
+One canonical resolver backs every lifecycle gate, `next`, `progress`, and reflection:
+
+1. latest valid structured diagnostic case (`DIAGNOSTIC_CASE_RECORDED`) for the active task/cycle;
+2. latest valid legacy diagnosis (`DIAGNOSIS_RECORDED`) for the active task/cycle;
+3. none.
+
+Structured diagnosis is therefore a first-class protocol-native diagnostic source: a task using only `record-diagnosis --file` can traverse `DIAGNOSING -> CORRECTING -> VERIFYING` without any legacy event, and no duplicate legacy event is synthesized. Legacy diagnosis remains fully valid as a compatibility input.
+
+## Hypothesis state projection
+
+Hypothesis status is projected forward from append-only chronology (case creation in `OPEN`, then each disposition validated against the last effective projected state) — never re-read from the source case. Terminal states (`FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`) do not transition unless a future protocol revision explicitly allows reopening. Invalid transitions fail closed with `E_HYPOTHESIS_DISPOSITION_INVALID`. `trace`, `reflect`, and continuity `openHypotheses` all consume this same projection.
+
+## Evidence binding
+
+Structured cases require at least one hypothesis; `CHECK_RESULT` observations must resolve to a real check from the active verification cycle; a `VERIFICATION_FAILURE` case must bind at least one hypothesis or observation to failed/blocked evidence from the active cycle. Revision chains are revalidated at read time (`revision N.previousDiagnosticFingerprint == revision N-1.diagnosticFingerprint`).
+
+## Effective gain definition
+
+Effective Information Gain exists when a diagnostic cycle changes a meaningful
+semantic dimension of the verified engineering state:
+
+```text
+new observation        new contributor       new hypothesis
+new evidence           hypothesis disposition hypothesis elimination
+failure signature      failure surface        intervention semantics
+strategy
+```
+
+All of these participate in `effectiveGain`. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never does.
+
+## Classification vs effective gain
+
+The compatibility classification (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`,
+`NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) intentionally does not
+encode every v2 dimension. A cycle can therefore report:
+
+```text
+classification = NONE
+failureSurfaceChanged = true
+effectiveGain = true
+```
+
+`effectiveGain` is computed once from the final dimensions by the authoritative
+cycle analysis projection; consumers (progress, reflect, next, inspect,
+continuity) must not recompute or post-mutate it.
+
+## Stall policy (fail-fast)
+
+A structured diagnostic state is **stalled** when its latest comparable
+diagnostic state has no effective information gain. There is no two-cycle
+threshold: one no-gain comparison blocks another blind correction retry with
+`E_DIAGNOSIS_NO_NEW_INFORMATION`, and progress/reflect/next/inspect expose the
+same condition. The first diagnosis is never stalled. High correction-cycle
+count alone remains advisory (`WATCH`), never `STALLED`.
+
+Stall is not terminal: recording a diagnostic with meaningful new information
+(a new observation, contributor, evidence, hypothesis change, and so on)
+clears it immediately. Strategy oscillation (`A -> B -> A`) keeps the more
+specific `INTRODUCE_NEW_OBSERVATION` guidance over generic no-gain guidance.
+Historical repetition metrics remain available as reflective explanation
+(`stallAnalysis`) but do not change the stall decision. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never counts as
+gain or as hypothesis elimination.
+
+## Failure surface evolution
+
+Every canonically verified cycle appears in failure surfaces, including
+successful ones:
+
+```text
+cycle 2 ["lint"]
+cycle 3 []        <- explicit empty successful cycle, direction REDUCED
+```
+
+A full reduction to `[]` classifies the preceding intervention as `IMPROVED`.
+
+## Intervention repetition
+
+```text
+repeatedSemanticIntervention
+  = the same intervention semantic fingerprint was recorded before
+
+NON_INFORMATIVE
+  = later verification produced no meaningful semantic change
+```
+
+Recording an intervention returns `repeatedSemanticIntervention` plus
+`effectiveness: "PENDING"`. Only a subsequent completed verification cycle can
+classify `IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`.
+
+## Continuity diagnostic context
+
+```json
+{
+  "activeFailureSignatures": ["<sha256-like canonical fingerprint>"],
+  "activeFailedRequirements": ["auth-tests"],
+  "openHypotheses": [],
+  "latestIntervention": null,
+  "nextExperiment": null,
+  "doNotRepeat": []
+}
+```
+
+`activeFailureSignatures` contains canonical `computeFailureSignature` hashes
+scoped to the active verification cycle; requirement names are exposed
+separately in `activeFailedRequirements`.
+
+## Structured case hypothesis invariant
+
+At least one hypothesis is mandatory: `hypotheses.minItems = 1` is enforced
+identically by the JSON schema, the runtime validator, ledger validation, and
+the record-diagnosis command path.
+
+## Information gain
+
+Compatibility values (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`, `NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) remain valid. Structured dimensions add observation/contributor/hypothesis novelty, disposition changes, failure-signature change, failure-surface change, and intervention change. New IDs, timestamps, whitespace, paraphrases, and identical reruns never constitute gain.
+
+## Stall and oscillation
+
+- High correction-cycle count alone is advisory (`WATCH`), never `STALLED`.
+- Strong stall requires identical failure signature, strategy, contributors, hypotheses, surface, and no new evidence across consecutive cycles. Two consecutive correction cycles without effective gain under the same strategy reach `STALLED` (`REQUIRE_NEW_DIAGNOSTIC_INFORMATION`).
+- Repetition of an intervention is not automatically non-informative: effectiveness (`PENDING | IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`) is classified only after subsequent verification. Continuity `doNotRepeat` requires semantic repetition AND at least two completed post-intervention verification cycles AND unchanged failure surface.
+- Oscillation (`A→B→A`) surfaces as `OSCILLATING_STRATEGY`; `next` recommends `INTRODUCE_NEW_OBSERVATION`.
+
+## Capability discovery
+
+`forgeloop protocol-info --json` advertises `features.diagnostics`, `executionHistory`, `structuredTrace`, `taskInspection`, and `reflection`.