@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,345 @@
+# ForgeLoop Troubleshooting Guide
+
+This guide provides symptom-first recovery procedures for common ForgeLoop protocol, state, and verification issues.
+
+---
+
+## Quick Symptom Index
+
+- [`preflight` is `BLOCKED`](#symptom-preflight-is-blocked)
+- [`forgeloop next` returns `RESOLVE_BLOCKER`](#symptom-forgeloop-next-returns-resolve_blocker)
+- [Protocol state or contract is `STALE`](#symptom-state-or-contract-is-stale)
+- [Execution continuity is `STALE`](#symptom-continuity-is-stale)
+- [Multiple tasks ambiguous (`E_TASK_AMBIGUOUS`)](#symptom-multiple-tasks-ambiguous)
+- [Verification tool is missing (`E_VERIFICATION_TOOL_UNAVAILABLE`)](#symptom-verification-tool-is-missing)
+- [Installation authority required (`E_INSTALLATION_AUTHORITY_REQUIRED`)](#symptom-installation-authority-required)
+- [Execution reference invalid (`E_EXECUTION_REF_INVALID`)](#symptom-execution-reference-invalid)
+- [`forgeloop complete` returns `INCOMPLETE`](#symptom-forgeloop-complete-returns-incomplete)
+- [`forgeloop complete` returns `INVALID`](#symptom-forgeloop-complete-returns-invalid)
+- [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
+- [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
+
+---
+
+## Symptoms and Recovery
+
+### Symptom: `preflight` is `BLOCKED`
+
+#### What it means
+
+Pre-implementation gates (e.g. `design`, `threat-boundary`) are unsatisfied, missing, or referencing stale files.
+
+#### Likely causes
+
+1. A gate required by an activated guide has no corresponding `.forgeloop/task-state/<taskKey>/gates/<gate>.json` file.
+2. The gate artifact references files whose SHA-256 hashes changed after the gate was satisfied.
+3. Contract `unresolvedDecisions` contains blocking decisions.
+
+#### Inspect
+
+```bash
+forgeloop task-show --task <id> --json
+forgeloop preflight --task <id> --json
+```
+
+#### Safe recovery
+
+1. If a gate is missing, satisfy required gates or create the gate artifact with status `"satisfied"`.
+2. If an artifact hash changed, update the artifact SHA-256 in the gate file.
+3. Re-run `forgeloop preflight --task <id> --json`.
+
+#### Do not
+
+Do not bypass preflight by manually editing `work-state.json`.
+
+---
+
+### Symptom: `forgeloop next` returns `RESOLVE_BLOCKER`
+
+#### What it means
+
+The protocol has encountered a condition that prevents automatic progression until an explicit blocker is resolved.
+
+#### Likely causes
+
+1. Task `work-state.json` was deleted or is out of sync with `contract.json`.
+2. A verification check failed and no diagnostic hypothesis was recorded.
+3. A required gate is unsatisfied.
+
+#### Inspect
+
+```bash
+forgeloop status --task <id> --json
+forgeloop next --task <id> --json
+```
+
+#### Safe recovery
+
+1. Check the `reasons` field in the `forgeloop next --json` output.
+2. Follow the suggested command in `commands` or `commandSpecs`.
+3. If in `VERIFYING` after a failure, record a hypothesis, apply the fix, and re-run `run-check`.
+
+---
+
+### Symptom: State or Contract is `STALE`
+
+#### What it means
+
+An upstream artifact was modified, invalidating downstream cryptographic fingerprint bindings.
+
+#### Likely causes
+
+1. `contract.json` was edited after `work-state.json` or `routing-result.json` was created (`E_CONTRACT_STALE`).
+2. Git `HEAD` changed (commit or checkout) while in `EXECUTING` or `VERIFYING`.
+
+#### Inspect
+
+```bash
+forgeloop task-show --task <id> --json
+forgeloop status --task <id> --json
+```
+
+#### Safe recovery
+
+1. If the contract changed intentionally:
+
+   ```bash
+   forgeloop route --task <id> --work <type> [options] --json
+   forgeloop preflight --task <id> --json
+   ```
+
+2. Re-validate state:
+
+   ```bash
+   forgeloop validate-protocol --task <id> --json
+   ```
+
+---
+
+### Symptom: Continuity is `STALE`
+
+#### What it means
+
+`.forgeloop/task-state/<taskKey>/continuity.json` references a previous `work-state.json` fingerprint or older checkout state.
+
+#### Likely causes
+
+Another harness or developer committed changes or advanced lifecycle phases without updating continuity.
+
+#### Inspect
+
+```bash
+forgeloop continuity --task <id> --json
+```
+
+#### Safe recovery
+
+1. Reconcile continuity with current state:
+
+   ```bash
+   forgeloop reconcile-continuity --task <id> --json
+   ```
+
+2. If continuity is obsolete, clear it:
+
+   ```bash
+   forgeloop clear-continuity --task <id>
+   ```
+
+   *Note: Clearing continuity does not lose lifecycle state; `work-state.json` remains intact.*
+
+---
+
+### Symptom: Multiple Tasks Ambiguous
+
+#### Error Code: `E_TASK_AMBIGUOUS`
+
+#### What it means
+
+Multiple active tasks exist in `.forgeloop/task-state/`, but the command was run without an explicit `--task` flag or `FORGELOOP_TASK` environment variable.
+
+#### Inspect
+
+```bash
+forgeloop task-list --json
+```
+
+#### Safe recovery
+
+Specify the task ID explicitly using the `--task` flag:
+
+```bash
+forgeloop status --task <task-id> --json
+forgeloop next --task <task-id> --json
+```
+
+Or set the environment variable for your shell session:
+
+```bash
+export FORGELOOP_TASK="<task-id>"
+```
+
+---
+
+### Symptom: Verification Tool is Missing
+
+#### Error Code: `E_VERIFICATION_TOOL_UNAVAILABLE`
+
+#### What it means
+
+A verification check requires an executable or tool that is not installed in the local environment.
+
+#### Likely causes
+
+1. The toolchain is missing a package or global binary (e.g. `linter`, `test runner`).
+2. Running in an isolated or sandboxed environment without network access.
+
+#### Safe recovery
+
+1. Use an already available local equivalent (e.g. `node scripts/run-tests.js` instead of an external runner).
+2. If an authorized host authority grant is available, install the tool.
+3. If no equivalent exists and installation is unauthorized, record the check as `NOT_VERIFIED` or `BLOCKED`.
+
+#### Do not
+
+**Do not run ad-hoc install commands (e.g. `npm i -g tool` or `npx tool`) without explicit operator authority.**
+
+---
+
+### Symptom: Installation Authority Required
+
+#### Error Code: `E_INSTALLATION_AUTHORITY_REQUIRED`
+
+#### What it means
+
+ForgeLoop intercepted a command that attempted to install software or fetch remote packages without a verified host authority grant.
+
+#### Likely causes
+
+Running `npx`, `npm install`, `yarn add`, or `pnpm add` during `run-check` or `record-check`.
+
+#### Safe recovery
+
+Use non-installing execution equivalents (e.g. `npm test`, `node <script>`, `./node_modules/.bin/<tool>`).
+
+---
+
+### Symptom: Execution Reference Invalid
+
+#### Error Code: `E_EXECUTION_REF_INVALID`
+
+#### What it means
+
+A check was claimed with a reference to an execution ID that does not exist in `.forgeloop/task-state/<taskKey>/executions/`.
+
+#### Safe recovery
+
+Execute the check through ForgeLoop CLI so that execution provenance is attested:
+
+```bash
+forgeloop run-check --task <id> --id <check-id> --requirement <requirement-id> -- <command...>
+```
+
+---
+
+### Symptom: `forgeloop complete` returns `INCOMPLETE`
+
+#### What it means
+
+One or more contract success criteria have not been covered by passing verification checks.
+
+#### Inspect
+
+```bash
+forgeloop audit --task <id> --json
+```
+
+Inspect the `coverage` array to find items with status `"NOT_VERIFIED"` or `"FAILED"`.
+
+#### Safe recovery
+
+1. Advance to `VERIFYING` if not already there:
+
+   ```bash
+   forgeloop advance --task <id> --to VERIFYING
+   ```
+
+2. Execute the missing check:
+
+   ```bash
+   forgeloop run-check --task <id> --id <id> --requirement <uncovered-requirement> -- <command...>
+   ```
+
+3. Advance to `REVIEWING` and retry `forgeloop complete --task <id> --json`.
+
+---
+
+### Symptom: `forgeloop complete` returns `INVALID`
+
+#### What it means
+
+Protocol integrity checks failed (e.g. ledger sequence error, missing contract deliverable, or hash mismatch).
+
+#### Inspect
+
+```bash
+forgeloop validate-protocol --task <id> --json
+```
+
+#### Safe recovery
+
+Inspect the specific error reported in `errors[]` and correct the inconsistent artifact.
+
+---
+
+### Symptom: Another Harness Cannot Resume
+
+#### Likely causes
+
+1. The new harness started by creating a new contract instead of discovering existing tasks via `task-list` or `status`.
+2. State is locked in a terminal or blocked condition.
+
+#### Safe recovery
+
+In the new harness:
+
+```bash
+# 1. Discover existing state
+forgeloop task-list --json
+forgeloop status --task <id> --json
+
+# 2. Reconcile continuity
+forgeloop reconcile-continuity --task <id> --json
+
+# 3. Ask for next action
+forgeloop next --task <id> --json
+```
+
+---
+
+## Stable Error and Reason Codes
+
+<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->
+
+| 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_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_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. |
+
+<!-- END FORGELOOP GENERATED: public-error-codes -->