@cassiomc1/forgeloop 1.2.3 → 1.3.0

package/docs/TROUBLESHOOTING.md

@@ -30,6 +30,15 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 
 ## Symptoms and Recovery
 
+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 -->
+```bash
+forgeloop protocol-info --json
+```
+<!-- END FORGELOOP EXAMPLE -->
+
 ### Symptom: `preflight` is `BLOCKED`
 
 #### What it means
@@ -563,56 +572,140 @@ forgeloop next --task <id> --json
 
 | Code | Meaning | Safe Resolution |
 | --- | --- | --- |
-| `E_PREFLIGHT_NOT_READY` | Preflight gates or contract validations are incomplete. | Satisfy required gates and check preflight output. |
-| `E_CONTRACT_STALE` | Contract modified after downstream artifacts were generated. | Re-run forgeloop route and forgeloop preflight. |
-| `E_ROUTE_STALE` | Routing result does not match the active contract fingerprint. | Re-run forgeloop route. |
-| `E_GATE_STALE` | Referenced gate artifact changed after approval. | Update artifact SHA-256 in gate file. |
-| `E_VERIFICATION_TOOL_UNAVAILABLE` | Required verification executable is missing in environment. | Use local equivalent, obtain host authority, or record NOT_VERIFIED. |
-| `E_INSTALLATION_AUTHORITY_REQUIRED` | Attempted software installation without host authority grant. | Use local non-installing binaries or request host authority grant. |
 | `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. |
-| `E_EXECUTION_REF_INVALID` | Referenced execution ID does not exist. | Re-run check via forgeloop run-check. |
+| `E_BASELINE_EXPANSION` | Attempted unauthorized addition of new violations to brownfield baseline. | Resolve new violations rather than expanding the baseline. |
+| `E_BASELINE_RECORD_DURING_ACTIVE_TASK` | Cannot re-record baseline during an active task with policy snapshot. | Resolve new violations or use monotonic baseline --update. |
+| `E_CHECK_INERT` | An enabled check has no effective scope or target files. | Provide an applicable target scope, configure matching files, or mark the rule unsupported. |
 | `E_CHECK_INVALID` | Check structure or required parameters are invalid. | Provide valid check ID, requirement, and parameters. |
-| `E_RECEIPT_STATE_MISMATCH` | Receipt does not match current state cycle or work state. | Run forgeloop prepare-completion --json. |
+| `E_CHECK_MUTATION_EXECUTION_ERROR` | A policy checker threw an unhandled exception while evaluating its mutation fixture. | Repair the checker execution path and rerun rule verification. |
+| `E_CHECK_MUTATION_NOT_DETECTED` | A blocking rule checker failed to detect an intentional mutation fixture. | Fix checker logic to properly identify target violations. |
+| `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_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. |
+| `E_COMPLETION_REJECTION_RECEIPT_FINGERPRINT_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_COMPLETION_REJECTION_STATE_FINGERPRINT_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_CONTINUITY_CONTRACT_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_CONTINUITY_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_CONTINUITY_PHASE_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_CONTINUITY_RECONCILIATION_REQUIRED` | Continuity context has drifted from work state. | Run forgeloop reconcile-continuity --json. |
-| `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_LOCKED` | Task mutation is currently locked by another concurrent process or run-check. | Wait for the active mutation to complete or inspect the lock with forgeloop task-show. |
-| `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_DIRTY` | Claimed paths contain pre-existing uncommitted changes. | Commit or stash changes in claimed paths before defining or adopting the scope. |
-| `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_RECONCILE_NOT_STALE` | reconcile-closure was invoked for a work-state checkpoint that is already fresh. | No reconciliation is required; continue the normal lifecycle. |
-| `E_RECONCILE_PHASE_INVALID` | reconcile-closure was invoked for a task that is not EXECUTING or VERIFYING. | reconcile-closure supports EXECUTING or VERIFYING tasks whose objective is already satisfied. |
-| `E_RECONCILE_UNSUPPORTED_DRIFT` | Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift). | Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift. |
-| `E_RECONCILE_LEDGER_INVALID` | The append-only event ledger is not valid, so reconciliation cannot be recorded. | Inspect the ledger errors and repair before reconciling. |
-| `E_RECONCILE_REQUIREMENT_UNKNOWN` | The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION. | Supply the exact id and requirement text of an existing contract verification item. |
-| `E_RECONCILE_EVIDENCE_FAILED` | The executed objective-satisfaction evidence command did not pass. | Inspect the execution artifact; reconciliation is refused until evidence passes in the current repository. |
-| `E_REPOSITORY_CHANGED` | The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded. | If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository. |
-| `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_DIAGNOSIS_REQUIRED` | Current correction cycle has no append-only diagnosis record. | Run forgeloop record-diagnosis with current failed evidence before correcting. |
-| `E_DIAGNOSIS_INVALID` | Diagnosis record details or parameters are malformed. | Provide valid failureClass, hypothesis, evidenceRefs, settledBy, and nextSafeAction. |
-| `E_DIAGNOSIS_EVIDENCE_INVALID` | Referenced diagnosis evidence is missing or has no failed checks in the current cycle. | Reference at least one failed or blocked check ID from the active verification cycle. |
-| `E_DIAGNOSIS_CYCLE_MISMATCH` | Diagnosis verification cycle does not match the active work state verification cycle. | Record diagnosis for the current active verification cycle. |
-| `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_PROGRESS_STALLED` | Persisted correction history shows no new diagnostic information. | Use an independent check, revisit assumptions, or record a materially different diagnosis. |
+| `E_CONTINUITY_SCHEMA_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_CONTINUITY_STATE_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_CONTINUITY_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_CONTRACT_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_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_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_CHECK_INERT` | An enabled check has no effective scope or target files. | Provide an applicable target scope, configure matching files, or mark the rule unsupported. |
-| `E_CHECK_MUTATION_NOT_DETECTED` | A blocking rule checker failed to detect an intentional mutation fixture. | Fix checker logic to properly identify target violations. |
-| `E_POLICY_DRIFT` | Active policy lock does not match the policy snapshot captured at task activation. | Re-verify affected checks or restore original policy. |
-| `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
-| `E_POLICY_LOCK_INVALID` | Policy lockfile is missing, malformed, or corrupt. | Run forgeloop policy-status or regenerate policy.lock. |
+| `E_DIAGNOSIS_CYCLE_MISMATCH` | Diagnosis verification cycle does not match the active work state verification cycle. | Record diagnosis for the current active verification cycle. |
+| `E_DIAGNOSIS_EVIDENCE_INVALID` | Referenced diagnosis evidence is missing or has no failed checks in the current cycle. | Reference at least one failed or blocked check ID from the active verification cycle. |
+| `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_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. |
+| `E_EVIDENCE_KIND_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_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_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_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_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_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_BASELINE_EXPANSION` | Attempted unauthorized addition of new violations to brownfield baseline. | Resolve new violations rather than expanding the baseline. |
-| `E_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
-| `E_CHECK_MUTATION_EXECUTION_ERROR` | A policy checker threw an unhandled exception while evaluating its mutation fixture. | Repair the checker execution path and rerun rule verification. |
+| `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. |
+| `E_POLICY_DRIFT` | Active policy lock does not match the policy snapshot captured at task activation. | Re-verify affected checks or restore original policy. |
+| `E_POLICY_DRIFT_UNKNOWN` | Task policy drift was detected but baseline snapshot details are unavailable. | Re-verify the task under the current policy state. |
 | `E_POLICY_EVALUATION_FAILED` | Policy evaluation threw an unexpected error during execution. | Inspect policy configuration and checker adapters for unhandled errors. |
+| `E_POLICY_INITIALIZATION_FAILED` | Executable policy bootstrap could not complete during initialization. | Repair the reported filesystem/schema error and rerun `forgeloop init`. Initialization is restartable while no committed manifest exists. |
 | `E_POLICY_INVALID` | Policy artifact is malformed, corrupt, or schema-invalid. | Validate and repair rules.json, baseline.json, or discovery.json against schema. |
-| `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
+| `E_POLICY_LOCK_INVALID` | Policy lockfile is missing, malformed, or corrupt. | Run forgeloop policy-status or regenerate policy.lock. |
 | `E_POLICY_LOCK_MISMATCH` | Persisted policy lock digest does not match current effective policy state. | Re-evaluate effective rules and update policy.lock or restore modified rules. |
-| `E_POLICY_DRIFT_UNKNOWN` | Task policy drift was detected but baseline snapshot details are unavailable. | Re-verify the task under the current policy state. |
-| `E_BASELINE_RECORD_DURING_ACTIVE_TASK` | Cannot re-record baseline during an active task with policy snapshot. | Resolve new violations or use monotonic baseline --update. |
-| `E_POLICY_INITIALIZATION_FAILED` | Executable policy bootstrap could not complete during initialization. | Repair the reported filesystem/schema error and rerun `forgeloop init`. Initialization is restartable while no committed manifest exists. |
-| `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_POLICY_PROOF_STALE` | Mutation verification proof is stale due to checker or fixture modifications. | Re-run forgeloop rule-verify to refresh mutation proof. |
+| `E_POLICY_SNAPSHOT_WRITE_FAILED` | Failed to persist task policy snapshot during preflight. | Ensure the target task directory is writable and repair filesystem permissions. |
+| `E_POLICY_WEAKENING` | Policy rules were weakened during task execution without explicit authority. | Restore the original policy configuration. |
+| `E_PREFLIGHT_EVENT_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_PREFLIGHT_GATES_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_PREFLIGHT_GATE_EVENT_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_PREFLIGHT_NOT_READY` | Preflight gates or contract validations are incomplete. | Satisfy required gates and check preflight output. |
+| `E_PREFLIGHT_READY_EVENT_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_PREFLIGHT_READY_EVENT_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_PRODUCTION_READINESS_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_PRODUCTION_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. |
+| `E_PROFILE_SOURCE_MISCLASSIFIED` | 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_SOURCE_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_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_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. |
+| `E_RECEIPT_CONTRACT_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_RECEIPT_CYCLE_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_RECEIPT_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_RECEIPT_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_RECEIPT_PATH_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_RECEIPT_ROUTE_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_RECEIPT_STATE_MISMATCH` | Receipt does not match current state cycle or work state. | Run forgeloop prepare-completion --json. |
+| `E_RECEIPT_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_RECONCILE_EVIDENCE_FAILED` | The executed objective-satisfaction evidence command did not pass. | Inspect the execution artifact; reconciliation is refused until evidence passes in the current repository. |
+| `E_RECONCILE_LEDGER_INVALID` | The append-only event ledger is not valid, so reconciliation cannot be recorded. | Inspect the ledger errors and repair before reconciling. |
+| `E_RECONCILE_NOT_STALE` | reconcile-closure was invoked for a work-state checkpoint that is already fresh. | No reconciliation is required; continue the normal lifecycle. |
+| `E_RECONCILE_PHASE_INVALID` | reconcile-closure was invoked for a task that is not EXECUTING or VERIFYING. | reconcile-closure supports EXECUTING or VERIFYING tasks whose objective is already satisfied. |
+| `E_RECONCILE_REQUIREMENT_UNKNOWN` | The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION. | Supply the exact id and requirement text of an existing contract verification item. |
+| `E_RECONCILE_UNSUPPORTED_DRIFT` | Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift). | Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift. |
+| `E_REPOSITORY_CHANGED` | The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded. | If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository. |
+| `E_ROUTE_GUIDE_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_ROUTE_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_ROUTE_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_ROUTE_REASON_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_ROUTE_STALE` | Routing result does not match the active contract fingerprint. | Re-run forgeloop route. |
+| `E_STATE_LEDGER_DIVERGENCE` | 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_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_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_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_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_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. |
+| `E_TASK_LAYOUT_LEGACY` | 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_LOCKED` | Task mutation is currently locked by another concurrent process or run-check. | Wait for the active mutation to complete or inspect the lock with forgeloop task-show. |
+| `E_TASK_LOCK_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_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_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_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. |
+| `E_TASK_SELECTOR_CONFLICT` | 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_NOT_TERMINAL` | 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_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. |
+| `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_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -59,12 +59,15 @@
   "scripts": {
     "test": "node scripts/run-tests.js",
     "pack:check": "node --test tests/package.test.js",
+    "pack:smoke": "node scripts/package_smoke.mjs",
     "release:identity": "node scripts/verify_release_identity.mjs",
     "docs:flow": "node scripts/generate-readme-flow.mjs",
     "docs:diagram:check": "node scripts/check-generated-diagram.mjs",
     "docs:generate": "node scripts/generate_documentation_reference.mjs --write",
     "docs:generated:check": "node scripts/generate_documentation_reference.mjs --check",
     "docs:conformance": "node scripts/validate_documentation_conformance.mjs",
+    "docs:examples:check": "node scripts/validate_documentation_examples.mjs",
+    "docs:report": "node scripts/report_documentation_health.mjs",
     "docs:check": "node scripts/run-docs-check.js",
     "lint": "eslint .",
     "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 node scripts/run-tests.js",

package/schemas/execution.schema.json

@@ -57,7 +57,17 @@
     "startedAt": { "type": "string", "minLength": 1 },
     "finishedAt": { "type": "string", "minLength": 1 },
     "status": { "enum": ["passed", "failed"] },
-    "exitCode": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }
+    "exitCode": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "termination": { "enum": ["exit", "signal", "timeout", "spawn-error"] },
+    "signal": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "stdoutSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "stderrSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "stdoutBytes": { "type": "integer", "minimum": 0 },
+    "stderrBytes": { "type": "integer", "minimum": 0 },
+    "outputTruncated": { "type": "boolean" }
+    ,"timeoutMs": { "type": "integer", "minimum": 1 }
+    ,"terminationGraceMs": { "type": "integer", "minimum": 1 }
   },
   "additionalProperties": false
 }

package/schemas/work-state.schema.json

@@ -59,6 +59,7 @@
     "failures": { "type": "array", "items": { "type": "object" } },
     "blockers": { "type": "array", "items": { "type": "object" } },
     "lastUpdated": { "type": "string", "minLength": 1 },
+    "revision": { "type": "integer", "minimum": 0 },
     "previousPhase": { "type": "string" },
     "diagnosedHypothesis": { "type": "string", "minLength": 1 },
     "verificationEvidence": { "type": "array", "items": { "type": "object" } },

package/src/cli.js

@@ -46,7 +46,10 @@ import { formatTaskListResult, runTaskList } from "./commands/task-list.js";
 import { formatTaskShowResult, runTaskShow } from "./commands/task-show.js";
 import { formatTaskScopeResult, runTaskScope } from "./commands/task-scope.js";
 import { formatTaskMigrateResult, runTaskMigrate } from "./commands/task-migrate.js";
+import { formatMigrateProtocolResult, runMigrateProtocol } from "./commands/migrate-protocol.js";
 import { formatTaskUnlockResult, runTaskUnlock } from "./commands/task-unlock.js";
+import { formatTaskLockStatusResult, runTaskLockStatus } from "./commands/task-lock-status.js";
+import { formatProtocolInfoResult, runProtocolInfo } from "./commands/protocol-info.js";
 import { continuityOptionDefaults, validateContinuityOptions } from "./core/continuity-cli-options.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
@@ -340,7 +343,7 @@ export function validateCliSemantics({ command, options } = {}) {
     if (!options.checkRequirement) throw new Error("run-check requires --requirement");
     if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
       || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw new Error("run-check accepts only --id, --requirement, --details, and -- <argv>");
+      throw new Error("run-check accepts only --id, --requirement, --details, --timeout-ms, and -- <argv>");
     }
     if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
       throw new Error("run-check requires -- followed by an exact command argv");
@@ -381,6 +384,11 @@ function printActions(actions) {
 }
 
 export const COMMAND_HANDLERS = Object.freeze({
+  "protocol-info": async ({ packageVersion, options }) => {
+    const result = await runProtocolInfo({ packageVersion });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatProtocolInfoResult(result));
+    return 0;
+  },
   init: async ({ target, packageRoot, packageVersion, options }) => {
     const result = await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion });
     printActions(result.actions);
@@ -482,6 +490,7 @@ export const COMMAND_HANDLERS = Object.freeze({
       requirement: options.checkRequirement,
       argv: options.commandArgv,
       details: options.checkDetails ?? undefined,
+      timeoutMs: options.timeoutMs ?? undefined,
       taskId: options.task,
     });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatRunCheckResult(result));
@@ -675,6 +684,11 @@ export const COMMAND_HANDLERS = Object.freeze({
     console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskShowResult(result));
     return 0;
   },
+  "task-lock-status": async ({ target, packageRoot, options }) => {
+    const result = await runTaskLockStatus({ target, packageRoot, taskId: options.task });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskLockStatusResult(result));
+    return 0;
+  },
   "task-scope": async ({ target, packageRoot, options }) => {
     const result = await runTaskScope({
       target,
@@ -690,8 +704,13 @@ export const COMMAND_HANDLERS = Object.freeze({
     console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskMigrateResult(result));
     return 0;
   },
+  "migrate-protocol": async ({ target, packageRoot, options }) => {
+    const result = await runMigrateProtocol({ target, packageRoot, to: options.to, dryRun: options.dryRun });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatMigrateProtocolResult(result));
+    return 0;
+  },
   "task-unlock": async ({ target, packageRoot, options }) => {
-    const result = await runTaskUnlock({ target, packageRoot, taskId: options.task, force: options.force });
+    const result = await runTaskUnlock({ target, packageRoot, taskId: options.task, force: options.force, staleOnly: options.staleOnly });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskUnlockResult(result));
     return 0;
   },

package/src/commands/doctor.js

@@ -4,6 +4,7 @@ import { readTemplateEntries } from "../core/templates.js";
 import { createEvidence } from "../core/evidence.js";
 import { LAYOUT_VERSION } from "../core/target-layout.js";
 import { inspectNativeAdapter, validateNativeAdapterTargets } from "../core/native-adapters.js";
+import { findIncompleteTransactions, recoverIncompleteTransactions } from "../core/transaction.js";
 
 function finding(code, severity, relativePath, message, remediation = null, evidence = null) {
   const evidenceRecord = evidence && typeof evidence === "object"
@@ -115,6 +116,27 @@ async function adoptAdapters({ target, manifest, adoptPaths, findings }) {
 
 export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false }) {
   const findings = [];
+  const incompleteTransactions = await findIncompleteTransactions(target);
+  for (const transaction of incompleteTransactions) {
+    findings.push(finding(
+      "E_TRANSACTION_INCOMPLETE",
+      "error",
+      `.forgeloop/.txn/${transaction.transactionId}`,
+      `Transaction ${transaction.transactionId} is ${transaction.status} and requires inspection or deterministic recovery.`,
+      "Run forgeloop doctor --fix only after ensuring no active process owns the task lock.",
+    ));
+  }
+  if (fix && incompleteTransactions.some((transaction) => transaction.status === "COMMITTING")) {
+    const recovered = await recoverIncompleteTransactions(target);
+    for (const transaction of recovered) {
+      findings.push(finding(
+        transaction.status === "ROLLED_BACK" ? "TRANSACTION_RECOVERED" : "E_TRANSACTION_RECOVERY_FAILED",
+        transaction.status === "ROLLED_BACK" ? "info" : "error",
+        `.forgeloop/.txn/${transaction.transactionId}`,
+        `Transaction recovery result: ${transaction.status}.`,
+      ));
+    }
+  }
   let manifest = null;
   let manifestChanged = false;
   try {

package/src/commands/migrate-protocol.js

@@ -0,0 +1,18 @@
+import { migrateProtocol } from "../core/protocol-migration.js";
+
+export async function runMigrateProtocol({ target, packageRoot, to, dryRun = false } = {}) {
+  return migrateProtocol(target, { to, dryRun, packageRoot });
+}
+
+export function formatMigrateProtocolResult(result) {
+  const lines = [
+    `target protocol: ${result.toProtocol}`,
+    `status: ${result.status}`,
+  ];
+
+  if (result.dryRun) lines.unshift("[dry-run]");
+  if (result.taskId) lines.push(`task: ${result.taskId}`);
+  if (result.targetDirectory) lines.push(`destination: ${result.targetDirectory}`);
+  lines.push(result.message ?? "legacy layout migration completed with a receipt");
+  return `${lines.join("\n")}\n`;
+}

package/src/commands/protocol-info.js

@@ -0,0 +1,16 @@
+import { protocolInfo } from "../core/protocol-info.js";
+
+export async function runProtocolInfo({ packageVersion = null } = {}) {
+  return protocolInfo({ packageVersion });
+}
+
+export function formatProtocolInfoResult(result) {
+  return [
+    `Package version: ${result.packageVersion ?? "unknown"}`,
+    `Protocol version: ${result.protocolVersion}`,
+    `Schema version: ${result.compatibility.schemaVersion}`,
+    `Commands: ${result.commands.length}`,
+    `Guides: ${result.guides.length}`,
+    `Documented errors: ${result.errors.length}`,
+  ].join("\n") + "\n";
+}

package/src/commands/run-check.js

@@ -12,6 +12,7 @@ export async function runCheck({
   requirement,
   argv,
   details,
+  timeoutMs,
   authorityContext,
   runtimeContext,
   taskId,
@@ -44,6 +45,7 @@ export async function runCheck({
       verificationCycle,
       argv,
       details,
+      timeoutMs,
       authorityContext,
       runtimeContext,
     });

package/src/commands/task-create.js

@@ -3,7 +3,8 @@ import { assertTaskId } from "../core/task-identity.js";
 import { createTaskDescriptor, writeTaskDescriptor } from "../core/task-descriptor.js";
 import { normalizeWriteClaims, assertNoScopeConflicts, assertScopeClean } from "../core/task-scope.js";
 import { discoverTasks, findTaskById } from "../core/task-discovery.js";
-import { withProjectClaimsLock, withTaskLock } from "../core/task-lock.js";
+import { withProjectClaimsLock } from "../core/task-lock.js";
+import { withTaskTransaction } from "../core/transaction.js";
 import { taskDirectory } from "../core/task-paths.js";
 import { ensureWithin, fileExists } from "../core/filesystem.js";
 import { validateContract, writeContract } from "../core/contract.js";
@@ -37,7 +38,7 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
       await assertScopeClean(target, normalizedClaims);
     }
 
-    return withTaskLock(target, taskId, "task-create", async () => {
+    return withTaskTransaction({ target, taskId, operation: "task-create", packageRoot, recordCommitEvent: true }, async () => {
       const descriptor = createTaskDescriptor({
         taskId,
         writeClaims: normalizedClaims,

package/src/commands/task-lock-status.js

@@ -0,0 +1,29 @@
+import { resolveTaskContext } from "../core/task-context.js";
+import { classifyLockStaleness, readLockInfo } from "../core/task-lock.js";
+
+export async function runTaskLockStatus({ target, packageRoot, taskId } = {}) {
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const lock = await readLockInfo(target, context.taskId);
+  if (!lock) {
+    return {
+      taskId: context.taskId,
+      taskKey: context.taskKey,
+      status: "UNLOCKED",
+      lock: null,
+      classification: null,
+    };
+  }
+  const classification = classifyLockStaleness(lock);
+  return {
+    taskId: context.taskId,
+    taskKey: context.taskKey,
+    status: classification.status,
+    lock,
+    classification,
+  };
+}
+
+export function formatTaskLockStatusResult(result) {
+  if (result.status === "UNLOCKED") return `Task ${result.taskId} is unlocked\n`;
+  return `Task ${result.taskId} lock: ${result.status} (${result.lock.operation ?? "unknown operation"})\n`;
+}

package/src/commands/task-show.js

@@ -1,6 +1,6 @@
 import { resolveTaskContext } from "../core/task-context.js";
 import { readTaskDescriptor } from "../core/task-descriptor.js";
-import { readLockInfo } from "../core/task-lock.js";
+import { classifyLockStaleness, readLockInfo } from "../core/task-lock.js";
 import { taskDirectory, taskArtifactPath } from "../core/task-paths.js";
 import { readWorkState } from "../core/work-state.js";
 import { readContract } from "../core/contract.js";
@@ -54,7 +54,7 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
     directory: taskDirectory(effectiveTaskId),
     phase: state?.phase ?? "UNINITIALIZED",
     writeClaims: descriptor.writeClaims ?? [],
-    lock: lockInfo,
+    lock: lockInfo ? { ...lockInfo, classification: classifyLockStaleness(lockInfo) } : null,
     contract: contract ? { title: contract.title ?? null, taskType: contract.taskType ?? null } : null,
     artifacts,
     createdAt: descriptor.createdAt,
@@ -65,7 +65,7 @@ export async function runTaskShow({ target, packageRoot, taskId } = {}) {
 export function formatTaskShowResult(result) {
   const claims = result.writeClaims.length === 0 ? "none" : result.writeClaims.join(", ");
   const lockStatus = result.lock
-    ? `locked by PID ${result.lock.pid ?? "unknown"} since ${result.lock.acquiredAt ?? "unknown"}`
+    ? `${result.lock.classification.status}: locked by PID ${result.lock.pid ?? "unknown"} since ${result.lock.acquiredAt ?? "unknown"}`
     : "unlocked";
   const lines = [
     `Task: ${result.taskId}`,

package/src/commands/task-unlock.js

@@ -1,7 +1,7 @@
 import { resolveTaskContext } from "../core/task-context.js";
-import { forceUnlockTask, readLockInfo } from "../core/task-lock.js";
+import { classifyLockStaleness, forceUnlockTask, readLockInfo } from "../core/task-lock.js";
 
-export async function runTaskUnlock({ target, packageRoot, taskId, force = false } = {}) {
+export async function runTaskUnlock({ target, packageRoot, taskId, force = false, staleOnly = false } = {}) {
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
   const effectiveTaskId = context.taskId;
 
@@ -15,18 +15,20 @@ export async function runTaskUnlock({ target, packageRoot, taskId, force = false
     };
   }
 
-  if (!force) {
+  const classification = classifyLockStaleness(lockInfo);
+  if (!force && !(staleOnly && classification.stale)) {
     const error = new Error(`Task ${effectiveTaskId} is locked by operation "${lockInfo.operation ?? "unknown"}" (PID ${lockInfo.pid ?? "unknown"}). Use --force to unlock.`);
     error.code = "E_TASK_LOCKED";
     throw error;
   }
 
-  await forceUnlockTask(target, effectiveTaskId);
+  const unlocked = await forceUnlockTask(target, effectiveTaskId, { staleOnly });
   return {
     taskId: effectiveTaskId,
     taskKey: context.taskKey,
-    unlocked: true,
-    message: `Released lock for task ${effectiveTaskId}`,
+    unlocked: unlocked.unlocked,
+    classification: unlocked.classification,
+    message: unlocked.unlocked ? `Released lock for task ${effectiveTaskId}` : `Task ${effectiveTaskId} lock is not stale`,
   };
 }