@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/docs/TROUBLESHOOTING.md

@@ -7,6 +7,7 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 ## Quick Symptom Index
 
 - [`preflight` is `BLOCKED`](#symptom-preflight-is-blocked)
+- [Project-aware .NET routing is missing](#symptom-project-aware-net-routing-is-missing)
 - [`forgeloop next` returns `RESOLVE_BLOCKER`](#symptom-forgeloop-next-returns-resolve_blocker)
 - [`forgeloop next` returns `RECORD_DIAGNOSIS`](#symptom-forgeloop-next-returns-record_diagnosis)
 - [Progress is `STALLED` or `forgeloop next` returns `CHANGE_STRATEGY`](#symptom-progress-is-stalled)
@@ -37,6 +38,7 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Repository search fails](#symptom-repository-search-fails)
 - [Persistent search host is unavailable](#symptom-persistent-search-host-is-unavailable)
 - [Persistent search host ownership is unverified or stale](#symptom-persistent-search-host-ownership-is-unverified-or-stale)
+- [Local validation tier is unavailable or reports `NOT_VERIFIED`](#symptom-local-validation-tier-is-unavailable-or-reports-not_verified)
 - [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)
@@ -54,6 +56,102 @@ forgeloop protocol-info --json
 ```
 <!-- END FORGELOOP EXAMPLE -->
 
+### Symptom: local validation tier is unavailable or reports `NOT_VERIFIED`
+
+#### What it means
+
+The selected local validation tier could not run a required external validator
+or setup prerequisite. `NOT_VERIFIED` is an explicit limitation, not a test
+pass and not permission to install tools implicitly.
+
+#### Safe recovery
+
+1. Check the tier and its command list with `node scripts/run-validation.mjs
+   --tier <fast|local|prepush|release> --list`.
+2. Run `npm run mcp:setup` explicitly when MCP dependencies are in scope and
+   installation is authorized.
+3. Confirm Python 3.9 or newer is available for the frozen validators.
+4. Re-run the tier and record any still-unavailable check as `NOT_VERIFIED` in
+   the validation report.
+
+The ordinary PR workflow remains path-aware and always publishes the required
+status contexts; its `validate (22)` aggregator fails closed on an applicable
+job failure, cancellation, or unexpected skip. Local success cannot substitute
+for a required remote security or cross-platform check.
+
+### Symptom: the Node.js test suite is slow locally
+
+#### Inspect
+
+Use the fast, watch, and CI-specific entry points before running the full
+coverage gate:
+
+```bash
+npm run test:quick
+npm run test:watch
+npm run test:ci
+npm run coverage
+```
+
+`npm test` remains the complete no-coverage suite. `test:ci` runs the same
+discovered files with a two-worker cap for small CI runners; it does not remove
+tests or change assertions. Local coverage remains an explicit command because
+instrumentation adds measurable overhead; the PR unit lane wraps that same
+`test:ci` process across four deterministic shards, then aggregates coverage
+without running the suite again. Docs-only changes run the quick suite only on
+the first Node 24 shard; the other shards and the Node 20 lane do not install.
+
+#### Native Windows guidance
+
+Repeated Node process startup can be slowed by Windows Defender scanning the
+repository and dependency tree. If local policy permits, request narrowly
+scoped exclusions for the trusted `node.exe`, this repository root, and its
+`node_modules` directory. Never disable Defender globally or exclude an
+untrusted path. WSL2 can be used when native Windows remains slow, while
+Windows CI continues to cover native path and process behavior.
+
+### Symptom: Project-aware .NET routing is missing
+
+#### What it means
+
+The route command did not find confirmed, affected SDK-style .NET project
+evidence, or the task scope does not reach the confirmed project root. ASP.NET
+Core and ABP are conditional overlays on the `dotnet` specialist; they are not
+standalone guides.
+
+#### Inspect
+
+```bash
+forgeloop route --task <task-id> --work code --surface backend --json
+forgeloop task-show --task <task-id> --json
+```
+
+Then inspect the affected scope for a structurally valid `*.csproj`, `*.fsproj`,
+or `*.vbproj` using the supported SDK allowlist. ASP.NET Core requires a web,
+Razor, or Blazor SDK or a `FrameworkReference Include="Microsoft.AspNetCore.App"`.
+ABP requires a structural `PackageReference Include="Volo.Abp..."` in the
+confirmed .NET project.
+
+#### Common causes
+
+- The repository contains only prose, source snippets, Dockerfiles, lockfiles,
+  package names, or a malformed/oversized/non-SDK-style project file.
+- A write claim points outside the project root, outside the applicable shared
+  `Directory.Build.*`/NuGet scope, or at a non-member of the named `.sln`/`.slnx`.
+- A mixed Flutter/.NET monorepo was treated as one root; nested project roots
+  remain isolated.
+- `projectEvidence.frameworks` contains `aspnetcore` or `abp` without
+  `dotnet`; route validation rejects that input.
+
+#### Safe recovery
+
+Do not add a manual `projectEvidence` claim to force specialist activation.
+Correct the task scope or project structure, rerun the canonical route command,
+and inspect its reason/exclusion codes. Project discovery is bounded and
+non-symlinked; budget exhaustion fails closed. See
+[`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) for the exact limits and reason-code
+contract.
+
 ### Symptom: `preflight` is `BLOCKED`
 
 #### What it means
@@ -1332,7 +1430,7 @@ package/process recovery boundary. The relevant stable codes are
 | `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_PHASE_INVALID` | reconcile-closure was invoked for a task that is not EXECUTING, VERIFYING, or REVIEWING. | reconcile-closure supports EXECUTING, VERIFYING, or REVIEWING 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. |
@@ -1372,7 +1470,7 @@ package/process recovery boundary. The relevant stable codes are
 | `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_REVALIDATION_REQUIRED` | The work-state checkpoint must be revalidated before the lifecycle can continue. | Run forgeloop reconcile-closure for externally satisfied EXECUTING, VERIFYING, or REVIEWING tasks, or inspect the freshness reasons for other drift. |
 | `E_STATE_TASK_MISMATCH` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_STRATEGY_OSCILLATION` | Correction history oscillates between previously exhausted strategies without new information. | Gather a genuinely new observation or test a materially different falsifiable hypothesis. |
 | `E_STRUCTURAL_QUALITY_BASELINE_BINDING_MISMATCH` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Reconcile contract, route, policy, scope, provider, or rules drift before using the baseline. |