@cassiomc1/forgeloop 1.6.3 → 1.6.4

package/docs/TROUBLESHOOTING.md

@@ -24,6 +24,11 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Policy weakening detected (`E_POLICY_WEAKENING`)](#symptom-policy-weakening-detected)
 - [Baseline re-record blocked during active task (`E_BASELINE_RECORD_DURING_ACTIVE_TASK`)](#symptom-baseline-re-record-blocked-during-active-task)
 - [Mutation checker execution error (`E_CHECK_MUTATION_EXECUTION_ERROR`)](#symptom-mutation-checker-execution-error)
+- [Workspace binding mismatch or invalid identity](#symptom-workspace-binding-mismatch-or-invalid-identity)
+- [Handoff is invalid or tampered](#symptom-handoff-is-invalid-or-tampered)
+- [Responsibility contract rejects a pass](#symptom-responsibility-contract-rejects-a-pass)
+- [Verification scope is stale or unresolved](#symptom-verification-scope-is-stale-or-unresolved)
+- [Attestation or revision coverage is invalid](#symptom-attestation-or-revision-coverage-is-invalid)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
 - [Task claim conflict or recovered task](#symptom-task-creation-blocked-by-a-write-claim-conflict-e_task_scope_conflict)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
@@ -726,6 +731,140 @@ A policy rule checker threw an unhandled exception while evaluating its syntheti
 
 ---
 
+### Symptom: Workspace Binding Mismatch or Invalid Identity
+
+#### Error Codes: `E_WORKSPACE_BINDING_MISMATCH`, `E_WORKSPACE_IDENTITY_UNAVAILABLE`, `E_WORKSPACE_BINDING_INVALID`
+
+#### What it means
+
+The task's optional workspace binding does not match the current repository or
+worktree, or the identity cannot be derived or parsed. A branch name or HEAD
+alone is not a complete workspace identity.
+
+#### Safe recovery
+
+Inspect the derived result and current task before changing anything:
+
+```bash
+forgeloop workspace-status --task <id> --json
+forgeloop status --task <id> --json
+forgeloop inspect --task <id> --json
+```
+
+Return to the bound checkout or create a deliberate new task/worktree. Do not
+edit `workspace-binding.json` manually or bypass the boundary. Rebinding is an
+explicit operation only when the task's scope permits it.
+
+---
+
+### Symptom: Handoff Is Invalid or Tampered
+
+#### Error Codes: `E_HANDOFF_INVALID`, `E_HANDOFF_STATE_UNAVAILABLE`, `E_HANDOFF_TAMPERED`, `E_HANDOFF_NOT_FOUND`
+
+#### What it means
+
+The immutable handoff envelope is malformed, its state is unavailable, its
+digest no longer matches, or the requested snapshot does not exist. A handoff
+note is not delegation, authority, independent review evidence, or completion
+evidence.
+
+#### Safe recovery
+
+```bash
+forgeloop handoff-list --task <id> --json
+forgeloop handoff-show --task <id> --id <handoffId> --json
+forgeloop continuity --task <id> --json
+forgeloop reconcile-continuity --task <id> --json
+```
+
+Use the last valid handoff or continuity only to focus inspection, then trust
+the canonical task state and checkout. Never repair a handoff by editing or
+deleting its JSON file.
+
+---
+
+### Symptom: Responsibility Contract Rejects a Pass
+
+#### Error Codes: `E_RESPONSIBILITY_INVALID`, `E_RESPONSIBILITY_SCOPE_VIOLATION`, `E_RESPONSIBILITY_FROZEN_INPUT_DRIFT`, `E_RESPONSIBILITY_REQUIRED_CHECK_MISSING`
+
+#### What it means
+
+An optional responsibility contract is malformed, a changed path is outside
+the allowed boundary, a frozen contract/route/claims input drifted, or a
+required check is missing. Its label is descriptive and does not represent a
+coder, reviewer, or cleaner role.
+
+#### Safe recovery
+
+```bash
+forgeloop responsibility-status --task <id> --json
+forgeloop inspect --task <id> --json
+forgeloop next --task <id> --json
+```
+
+Restore the declared scope or create a new explicit responsibility decision
+through `responsibility-set`. Do not widen the JSON artifact manually and do
+not relabel the pass to bypass enforcement.
+
+---
+
+### Symptom: Verification Scope Is Stale or Unresolved
+
+#### Error Codes: `E_VERIFICATION_SCOPE_INVALID`, `E_VERIFICATION_SCOPE_STALE`, `E_VERIFICATION_SCOPE_UNRESOLVED`
+
+#### What it means
+
+The scope is malformed or no longer matches the task's cycle, claims, contract,
+repository fingerprint, changed paths, or checker capability. `CHANGED` and
+`CLAIMED` require a trusted scoped checker; `AUTO` uses those modes only when
+they can be proved and otherwise resolves to `FULL`. There is no heuristic
+`IMPACTED` mode.
+
+#### Safe recovery
+
+```bash
+forgeloop verify-scope --task <id> --mode AUTO --json
+forgeloop run-check --task <id> --id <checkId> \
+  --requirement "<requirement>" \
+  --scope-ref .forgeloop/task-state/<taskKey>/verification-scope.json \
+  -- <exact-argv-prefix-and-paths>
+```
+
+If no trusted scoped checker is configured, run a full check or record the
+scope as unresolved. An exact argv or selected-path mismatch is rejected before
+launch; do not retry with guessed paths or edit the scope artifact.
+
+---
+
+### Symptom: Attestation or Revision Coverage Is Invalid
+
+#### Error Codes: `E_ATTESTATION_MANIFEST_INVALID`, `E_ATTESTATION_MANIFEST_STALE`, `E_ATTESTATION_STATEMENT_INVALID`, `E_ATTESTATION_UNSIGNED`, `E_ATTESTATION_SIGNATURE_INVALID`, `E_ATTESTATION_SIGNER_UNAVAILABLE`, `E_ATTESTATION_IDENTITY_UNTRUSTED`, `E_ATTESTATION_ISSUER_UNTRUSTED`, `E_ATTESTATION_COVERAGE_GAP`, `E_ATTESTATION_COVERAGE_CONFLICT`, `E_REVISION_PROVIDER_UNAVAILABLE`, `E_REVISION_CONTENT_UNAVAILABLE`
+
+#### What it means
+
+The exact source-content manifest, completion/ledger binding, in-toto
+statement, signer policy, revision provider, or range coverage is missing,
+stale, invalid, unavailable, or conflicting. `PROCESSED` is not `VERIFIED`,
+and `VERIFIED` is not `ATTESTED` without a valid external signature.
+
+#### Safe recovery
+
+Use read-only inspection first:
+
+```bash
+forgeloop attestation-status --task <id> --json
+forgeloop attestation-verify --task <id> --ref HEAD --json
+forgeloop attestation-verify-range --revision-provider git \
+  --base origin/main --head HEAD --require-complete-coverage --json
+```
+
+Correct the named source or provider boundary through its canonical lifecycle.
+Uncovered paths and conflicting task digests fail closed; an unavailable signer
+does not become a valid signature. Never edit a manifest, statement, receipt,
+ledger, or signature bundle manually, and never persist credentials in them.
+
+---
+
 ### Symptom: Another Harness Cannot Resume
 
 #### Likely causes
@@ -780,6 +919,31 @@ forgeloop next --task <id> --json
 | `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_ATTESTATION_CONFIGURATION_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_CONTENT_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_CONTRACT_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_COVERAGE_CONFLICT` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_COVERAGE_GAP` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_DISABLED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_GIT_REQUIRED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_IDENTITY_UNTRUSTED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_ISSUER_UNTRUSTED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_LEDGER_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_MANIFEST_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_MANIFEST_MISSING` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_MANIFEST_STALE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_RECEIPT_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_ROUTE_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_SCOPE_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_SIGNATURE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_SIGNER_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_STATEMENT_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_STATEMENT_MISSING` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_STATE_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_SUBJECT_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_TARGET_REF_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_ATTESTATION_UNSIGNED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `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. |
@@ -791,6 +955,7 @@ forgeloop next --task <id> --json
 | `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_CLI_INVOCATION_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_COMMAND_RESOLUTION_AMBIGUOUS` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_COMPLETION_OWNERSHIP_UNPROVEN` | Work-state claims COMPLETE but the canonical lifecycle/ledger completion proof is missing or invalid, so historical claims stay reserved. | Restore the canonical completion event and a valid ledger, or re-run the official completion pipeline; phase=COMPLETE alone never releases claims. |
 | `E_COMPLETION_RECOVERY_UNAUTHORIZED` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -835,6 +1000,10 @@ forgeloop next --task <id> --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_HANDOFF_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_HANDOFF_NOT_FOUND` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_HANDOFF_STATE_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_HANDOFF_TAMPERED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `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. |
@@ -897,6 +1066,15 @@ forgeloop next --task <id> --json
 | `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_RESPONSIBILITY_FROZEN_INPUT_DRIFT` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_RESPONSIBILITY_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_RESPONSIBILITY_REQUIRED_CHECK_MISSING` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_RESPONSIBILITY_SCOPE_VIOLATION` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_REVISION_CONTENT_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_REVISION_NOT_FOUND` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_REVISION_PROVIDER_AMBIGUOUS` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_REVISION_PROVIDER_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_REVISION_PROVIDER_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `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. |
@@ -947,6 +1125,12 @@ forgeloop next --task <id> --json
 | `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_EXECUTION_INVALID` | The trusted verification execution adapter returned incomplete or invalid execution metadata. | Repair the adapter contract and rerun verification; do not promote incomplete execution evidence. |
 | `E_VERIFICATION_ISOLATION_UNAVAILABLE` | Verification cannot run because the required disposable or system isolation boundary is unavailable. | Use a trusted ForgeLoop execution adapter with the required isolation mode; never run the check in the live project. |
+| `E_VERIFICATION_SCOPE_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_VERIFICATION_SCOPE_STALE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_VERIFICATION_SCOPE_UNRESOLVED` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_VERIFICATION_TOOL_UNAVAILABLE` | Required verification executable is missing in environment. | Use local equivalent, obtain host authority, or record NOT_VERIFIED. |
+| `E_WORKSPACE_BINDING_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_WORKSPACE_BINDING_MISMATCH` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
+| `E_WORKSPACE_IDENTITY_UNAVAILABLE` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 
 <!-- END FORGELOOP GENERATED: public-error-codes -->

package/docs/UNIVERSAL_INTEGRATION.md

@@ -46,3 +46,14 @@ import {
 All consumers share one protocol authority: `.forgeloop/` state written only
 by canonical ForgeLoop commands, so cross-harness continuity and recovery work
 identically regardless of transport.
+
+Optional integrations use the same ownership boundary. ForgeLoop derives and
+validates workspace bindings, immutable handoffs, responsibility constraints,
+verification scopes, execution evidence, code manifests, attestation
+statements, and provider results. The embedding host owns checkout selection,
+model/tool execution, scheduling, transport, external signer credentials, and
+platform presentation. A handoff or continuity note never becomes evidence;
+`CHANGED`/`CLAIMED` verification scope never becomes revision-range coverage;
+and only a validated external signature can raise `VERIFIED` to `ATTESTED`.
+These extensions are optional and do not change the zero-configuration basic
+loop.