@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/docs/TEST_INTELLIGENCE.md

@@ -0,0 +1,29 @@
+# Test intelligence
+
+ForgeLoop discovers test units deterministically and assigns stable IDs from
+framework, path, suite, and trimmed name. Utility analysis is non-evidence
+data. The task-bound utility command sends bounded batches of actual test
+metadata (including source summary, target file, framework, signals, and
+runtime or branch-coverage fields when present; deterministic inventory
+currently supplies them as `null`) to canonical Jev `TEST_UTILITY` decisions.
+Each test receives its own bounded semantic judgment. Protected or
+contract-linked tests are never prune-authorized, and missing or low-confidence
+utility remains blocked.
+
+An unprotected semantic duplicate with sufficient confidence is classified as a
+`REDUNDANT_CANDIDATE` and may reach the isolated `PROBE_REMOVAL` stage. The
+probe is non-destructive and does not authorize deletion; protected tests,
+low-confidence candidates, unknown utility, and candidates requiring a second
+review remain blocked or retained.
+
+`test-utility` persists the non-evidence `test-utility.json` analysis under
+the task namespace. The canonical task mutation may also persist bounded
+semantic-decision artifacts and task transaction or ledger state required to
+make the analysis task-bound and reproducible. It does not delete tests, alter
+completion evidence, or authorize external work.
+
+`npm run benchmark:test-intelligence` exercises the real utility classifier on
+a deterministic labeled fixture for redundancy, obsolescence, protected-test
+false positives, and deletion safety. It reports precision and recall from the
+classifier's observed output against the labeled fixture and never grants
+deletion authority.

package/docs/TEST_PRUNING.md

@@ -0,0 +1,14 @@
+# Test pruning safety
+
+`test-prune-plan` can return `KEEP`, `PROBE_REMOVAL`, or `BLOCKED`.
+`PROBE_REMOVAL` requires both protected-test policy and sufficient deterministic
+and semantic evidence. Unknown utility is `BLOCKED`.
+
+The safe candidate boundary is an unprotected, high-confidence
+`REDUNDANT_CANDIDATE`. Protected tests and low-confidence or ambiguous
+recommendations remain `KEEP`/`BLOCKED`. The isolated probe is
+non-destructive: it records an observation without editing the live worktree
+or authorizing deletion.
+
+`test-prune-probe` is fail-closed and must use an isolated disposable workspace.
+No command in this feature deletes or edits a test in the live working tree.

package/docs/TROUBLESHOOTING.md

@@ -7,10 +7,12 @@ 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)
 - [Protocol state or contract is `STALE`](#symptom-state-or-contract-is-stale)
+- [A pre-execution checkpoint is stale because the repository moved](#symptom-a-pre-execution-checkpoint-is-stale-because-the-repository-moved)
 - [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)
@@ -37,6 +39,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 +57,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
@@ -231,6 +330,73 @@ the blocked preflight is resolved, `preflight` appends a fresh
 details differ *without* an intervening BLOCKED outcome is still refused with
 `E_PHASE_CHRONOLOGY_INVALID`.
 
+### Symptom: A pre-execution checkpoint is stale because the repository moved
+
+#### What it means
+
+A `ROUTED` checkpoint has valid ownership, contract identity, route identity,
+and no execution history, but its recorded repository branch or HEAD differs
+from the current checkout. `next` returns `REVALIDATE_CHECKPOINT` with
+`E_REPOSITORY_CHANGED` and `E_STATE_REVALIDATION_REQUIRED`.
+
+#### Safe recovery
+
+Run the canonical mutation:
+
+```bash
+forgeloop checkpoint-revalidate --task <id> --json
+forgeloop next --task <id> --explain --json
+```
+
+The command derives the repository fingerprint from ForgeLoop while holding
+the task mutation boundary. It preserves the phase, contract fingerprint,
+route fingerprint, selected guides, gates, checks, and evidence. It does not
+revise the contract, reroute the task, fabricate continuity or receipt
+artifacts, or operate after `EXECUTION_STARTED`.
+
+If the command fails with `E_CHECKPOINT_REVALIDATION_UNSAFE`, follow the named
+contract, route, artifact, ownership, or lifecycle boundary. Do not edit
+`work-state.json`, pass a caller-supplied branch or HEAD, or use
+`reconcile-closure` for a `ROUTED` task.
+
+---
+
+### Symptom: The task contract must change before execution
+
+#### What it means
+
+The task is still before execution, but its objective, deliverables, or
+constraints have changed. Existing route, preflight, gate, and plan evidence
+must not authorize the new contract.
+
+#### Safe recovery
+
+Use exactly one bounded replacement source:
+
+```bash
+forgeloop contract-revise --task <id> --preset <documentation|bug|feature|release> --json
+forgeloop contract-revise --task <id> --contract-file <path> --json
+```
+
+The command appends `CONTRACT_REVISED` followed immediately by
+`TRANSACTION_COMMITTED(operation=contract-revise)`, resets derived evidence,
+and preserves the task descriptor claims. A `ROUTED` task must be routed and
+preflighted again; a `PLANNED` task is rewound to `ROUTED` and must receive a
+fresh canonical route, preflight, and plan. Historical checkpoint identity
+remains valid only when later contract and route evolution is proven by the
+canonical append-only provenance chain.
+
+`previousStateFingerprint` and `revisedStateFingerprint` on `CONTRACT_REVISED`
+are transition-time audit bindings. They are checked when the revision is the
+current state transition and participate in append-only event integrity; they
+are not treated as permanently frozen current-state identity after later
+canonical mutations.
+
+Contract revision is unavailable after `EXECUTION_STARTED` and for active
+contract-bootstrap repair or migration anchors. Do not rewrite the contract,
+state, route, or ledger files manually. If `next` reports a stale route,
+reroute it with the normal `route` command before running preflight.
+
 ---
 
 ### Symptom: `EXECUTING`/`VERIFYING` task is stale because the repository moved (`E_REPOSITORY_CHANGED`)
@@ -248,7 +414,7 @@ forgeloop reconcile-closure --task <id> --id <verification-id> \
 
 `reconcile-closure` requires:
 
-1. The task is `EXECUTING`, `VERIFYING`, or `REVIEWING`. A `REVIEWING` task additionally requires authorized completion recovery (a persisted evidence-only rejection bound to the current checkpoint), or a rejection snapshot that can be rebound (see below).
+1. The task is `EXECUTING`, `VERIFYING`, or `REVIEWING`. A `REVIEWING` task may use authorized completion recovery (a persisted evidence-only rejection bound to the current checkpoint), or, when no completion rejection exists, the narrow bootstrap path for repository-only drift. The bootstrap path does not change phase, append completion events, or release claims.
 2. The only drift is `REPOSITORY_CHANGED` (contract or required-artifact drift stays blocked).
 3. The append-only event ledger is valid.
 4. `--id` and `--requirement` exactly match a `VERIFICATION` item of the task contract, and the executed command exits 0, proving the objective is present in the current repository.
@@ -263,6 +429,12 @@ forgeloop advance --task <id> --to REVIEWING
 forgeloop complete --task <id>
 ```
 
+The bootstrap path is intentionally narrower than completion recovery: contract
+identity, required artifacts, ledger validity, and active claim ownership must
+already be valid, and the freshness classifier must report exactly
+`REPOSITORY_CHANGED`. Contract or artifact drift remains blocked and must use
+its dedicated canonical recovery surface.
+
 #### Drifted completion-rejection snapshots (`E_COMPLETION_REJECTION_STATE_FINGERPRINT_MISMATCH`)
 
 A `REVIEWING` task with a persisted evidence-only completion rejection can lose
@@ -389,6 +561,38 @@ corrupt, or unreadable evidence fails closed as `INCONSISTENT`. A `REVIEWING`
 phase plus an old timestamp alone is never `STALE`; post-execution tasks whose
 only drift is `REPOSITORY_CHANGED` remain `RECOVERABLE`.
 
+#### Contract bootstrap repair
+
+When `next` reports `REPAIR_CONTRACT_BOOTSTRAP`, do not edit `events.ndjson` or
+`work-state.json`. Run the official, explicitly acknowledged repair:
+
+```bash
+forgeloop task-repair-contract-bootstrap --task <task-id> --acknowledge-repair --json
+```
+
+Only the exact duplicate `CONTRACT_VALIDATED` signature is accepted. The command
+preserves historical lines, reconstructs the proven `CONTRACT_READY` or `ROUTED`
+checkpoint, and records an append-only marker. Tampered artifacts, unrelated
+chronology errors, live locks, or later meaningful activity fail closed.
+If the ledger already contains `ROUTE_VALIDATED`, the route artifact is
+required and must remain valid and contract-bound; ForgeLoop never downgrades
+that history to `CONTRACT_READY`. After repair, a changed route identity is
+accepted only when the route/state pair is canonical and a later
+`TRANSACTION_COMMITTED` event has `operation: "route"`.
+
+When `next` reports `MIGRATE_CONTRACT_BOOTSTRAP_REPAIR`, run the official
+caller-acknowledged migration:
+
+```bash
+forgeloop task-migrate-contract-bootstrap-repair --task <task-id> --acknowledge-migration --json
+```
+
+This path is limited to the legacy marker schema that predates
+`reconstructedStateRevision`. It proves the current state and route against the
+recorded reconstruction, appends a bound migration witness, and preserves the
+legacy marker byte-for-byte. It does not accept progressed ledgers, ambiguous
+markers, or unknown/corrupt lock ownership.
+
 #### Safe recovery
 
 Follow the classification:
@@ -1134,6 +1338,25 @@ package/process recovery boundary. The relevant stable codes are
 `E_PERSISTENT_TRANSPORT_HOST_STALE`, and
 `E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH`.
 
+### Symptom: Security Review provider is unavailable or rejected
+
+#### Error Codes: `E_SECURITY_REVIEW_PROVIDER_INVALID`, `E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE`, `E_SECURITY_REVIEW_REQUEST_INVALID`, `E_SECURITY_REVIEW_RESULT_INVALID`, `E_SECURITY_REVIEW_TIMEOUT`, `E_SECURITY_REVIEW_CANCELLED`, `E_SECURITY_REVIEW_OUTPUT_LIMIT`, `E_SECURITY_REVIEW_EXECUTION_FAILED`
+
+#### What it means
+
+The optional Security Review Integration API provider was not registered,
+failed the strict provider/request/result contract, exceeded its shared
+deadline or output budget, was cancelled, or threw during observation. This
+surface is advisory and never blocks or authorizes ForgeLoop lifecycle.
+
+#### Safe recovery
+
+Register an explicit host-owned provider with a matching portable ID, use
+bounded project-relative request paths and limits, and make the provider honor
+the supplied `AbortSignal`. Do not install or discover a scanner through
+ForgeLoop, and do not treat findings as evidence, completion, commands, or
+canonical task state.
+
 ## Stable Error and Reason Codes
 
 <!-- BEGIN FORGELOOP GENERATED: public-error-codes -->
@@ -1200,6 +1423,17 @@ package/process recovery boundary. The relevant stable codes are
 | `E_AUTHORITY_UNTRUSTED_SOURCE` | Authority file placed inside untrusted project tree. | Place authority file in host-managed trusted location. |
 | `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_BROWSER_VERIFICATION_CANCELLED` | Browser verification was cancelled by its caller before a valid observation completed. | Retry only when the caller still requires the optional observation. |
+| `E_BROWSER_VERIFICATION_EXECUTION_FAILED` | The optional browser provider process failed without establishing a valid observation. | Inspect the host-provided browser executable and retry; process success is not verification success. |
+| `E_BROWSER_VERIFICATION_ORIGIN_DENIED` | Browser verification navigation left the request origin allowlist. | Add the intended origin to allowedOrigins or correct the provider navigation result. |
+| `E_BROWSER_VERIFICATION_OUTPUT_LIMIT` | Browser verification output exceeded the configured character or item limit. | Reduce steps, assertions, snapshots, diagnostics, or artifacts at the provider. |
+| `E_BROWSER_VERIFICATION_PROVIDER_INVALID` | Browser verification provider configuration or interface implementation is invalid. | Use a provider implementing id, verify(input) with the documented browser-verification contract; verification is optional. |
+| `E_BROWSER_VERIFICATION_PROVIDER_UNAVAILABLE` | Requested browser verification provider is not registered in runtime context. | Register the provider in runtime context before verify, or proceed without browser verification; provider failure never blocks canonical lifecycle. |
+| `E_BROWSER_VERIFICATION_REQUEST_INVALID` | Browser verification request failed validation or exceeded budget. | Provide a bounded request with 1-8 https origins, 1-64 steps, 1-64 assertions, and timeoutMs within limits. |
+| `E_BROWSER_VERIFICATION_RESULT_INVALID` | Browser verification provider returned an invalid result structure. | Ensure provider returns a status with bounded assertions, diagnostics, and artifacts, and no authority fields. |
+| `E_BROWSER_VERIFICATION_TIMEOUT` | Browser verification exceeded its execution timeout. | Use a responsive provider or increase timeout within limits; verification is optional. |
+| `E_BROWSER_VERIFICATION_VERSION_UNSUPPORTED` | The configured Agent Browser version does not satisfy the provider's exact version contract. | Provide the expected host-qualified Agent Browser version or update the explicit executable selection. |
+| `E_CHECKPOINT_REVALIDATION_UNSAFE` | A pre-execution checkpoint could not be safely rebound to the current repository without changing lifecycle identity. | Preserve the checkpoint and resolve the reported contract, route, ownership, artifact, or lifecycle boundary through its canonical command. |
 | `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_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. |
@@ -1221,14 +1455,39 @@ package/process recovery boundary. The relevant stable codes are
 | `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_BOOTSTRAP_INCONSISTENT` | Contract bootstrap evidence is inconsistent and cannot be treated as a normal idempotent checkpoint. | Inspect the task ledger and use the exact official contract bootstrap repair only when next recommends it. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_AUTHORIZATION_REQUIRED` | The official contract bootstrap repair requires explicit caller acknowledgement. | Re-run with --acknowledge-repair after reviewing next and the exact defect signature. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_AVAILABLE` | The exact recognized contract bootstrap defect has an official append-only repair path. | Run forgeloop task-repair-contract-bootstrap --task <id> --acknowledge-repair. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_INVALID` | The contract bootstrap repair marker or its bound artifacts are invalid or tampered. | Restore the original artifacts from trusted evidence; ForgeLoop refuses to guess or rewrite history. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AUTHORIZATION_REQUIRED` | The legacy contract bootstrap repair migration requires fresh explicit caller acknowledgement. | Re-run with --acknowledge-migration after reviewing next and the exact legacy marker boundary. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_AVAILABLE` | The exact legacy contract bootstrap repair marker has an official append-only migration path. | Run forgeloop task-migrate-contract-bootstrap-repair --task <id> --acknowledge-migration. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID` | Legacy contract bootstrap repair migration was refused because its exact marker, state, route, lock, or ledger boundary could not be proven. | Inspect the structured migration errors; ambiguous or progressed historical ledgers remain inconsistent and are never rewritten. |
+| `E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE` | The historical contract bootstrap defect does not satisfy the narrow repair safety boundary. | Do not force repair; resolve the ledger inconsistency through a separately reviewed migration. |
 | `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_CONTRIBUTOR_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_CONTRIBUTOR_REFERENCE_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_DECISION_CACHE_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_DECISION_CRITERION_INVALID` | Decision settlement criterion details or parameters are malformed. | Provide non-empty decision text and settledBy criterion. |
+| `E_DECISION_ENGINE_AUTH_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_DECISION_ENGINE_AUTH_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_DECISION_ENGINE_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_DECISION_LOW_CONFIDENCE` | 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_MODEL_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_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_DECISION_POLICY_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_DECISION_QUESTION_SET_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_DECISION_QUESTION_SET_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_DECISION_RATE_LIMITED` | 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_REQUEST_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_DECISION_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_DECISION_RESULT_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_DECISION_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_DECISION_STATE_LIMIT` | 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_STATE_UNSAFE` | 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_TIMEOUT` | 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_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. |
@@ -1252,6 +1511,8 @@ package/process recovery boundary. The relevant stable codes are
 | `E_FAILURE_SIGNATURE_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_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_INVALID` | Gate input or evidence artifact is invalid or unsafe. | Use project-relative regular artifact paths and valid gate evidence. |
+| `E_GATE_NOT_REQUIRED` | Requested gate is not required by the active route or policy. | Inspect the active route and record only a required gate. |
 | `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. |
@@ -1291,6 +1552,7 @@ package/process recovery boundary. The relevant stable codes are
 | `E_PERSISTENT_TRANSPORT_TIMEOUT` | A persistent-search connection, handshake, or request exceeded its bounded timeout. | Retry once through the ownership-checked recovery path and inspect host/index health if it persists. |
 | `E_PERSISTENT_TRANSPORT_UNAVAILABLE` | The user-scoped persistent-search endpoint was not reachable. | ForgeLoop starts one verified local host and retries once; persistent failure is reported without an rg fallback. |
 | `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_FREEZE` | The requested gate mutation is forbidden after execution begins. | Record required gates before entering EXECUTING. |
 | `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. |
@@ -1332,7 +1594,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. |
@@ -1369,10 +1631,18 @@ package/process recovery boundary. The relevant stable codes are
 | `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_SECURITY_REVIEW_CANCELLED` | Security review provider execution was cancelled before a valid observation completed. | Retry only when the caller still requires the optional observation. |
+| `E_SECURITY_REVIEW_EXECUTION_FAILED` | The optional security review provider failed without producing a valid observation. | Inspect the host-provided provider and retry explicitly; provider failure never changes ForgeLoop state. |
+| `E_SECURITY_REVIEW_OUTPUT_LIMIT` | Security review provider output exceeded the bounded result limits. | Reduce findings, diagnostics, strings, or result size at the provider. |
+| `E_SECURITY_REVIEW_PROVIDER_INVALID` | Security review provider configuration or interface implementation is invalid. | Use a provider implementing id and review(input) through the explicit host-injected Integration API. |
+| `E_SECURITY_REVIEW_PROVIDER_UNAVAILABLE` | The requested security review provider is not registered in runtime context. | Register an optional host-owned provider before explicit invocation; ForgeLoop never installs one. |
+| `E_SECURITY_REVIEW_REQUEST_INVALID` | The bounded security review request failed validation. | Provide explicit scope, bounded project-relative paths, categories, requirements, identities, and timeout. |
+| `E_SECURITY_REVIEW_RESULT_INVALID` | The security review provider returned malformed or contradictory findings. | Return only bounded findings and diagnostics without authority, lifecycle, evidence, or executable fields. |
+| `E_SECURITY_REVIEW_TIMEOUT` | Security review provider execution exceeded the shared deadline. | Use a responsive provider or a bounded timeout within the supported limit; timed-out output is discarded. |
 | `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. |
@@ -1396,6 +1666,11 @@ package/process recovery boundary. The relevant stable codes are
 | `E_STRUCTURAL_QUALITY_SOURCE_DRIFT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Ensure the worktree is not mutated during provider observation and rerun quality-baseline or quality-verify. |
 | `E_STRUCTURAL_QUALITY_SOURCE_FINGERPRINT_UNAVAILABLE` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Repair unreadable or unsafe source material before structural-quality evidence can be trusted. |
 | `E_STRUCTURAL_QUALITY_TIMEOUT` | Structural-quality evidence did not satisfy its provider, artifact, comparison, or lifecycle boundary. | Use a responsive provider or a bounded timeout within the supported limit; never promote a timed-out scan. |
+| `E_TASK_ABANDON_AUTHORIZATION_REQUIRED` | task-abandon requires explicit caller acknowledgement and never grants completion or publication authority. | Re-run task-abandon with --acknowledge-abandonment after confirming the explicit task identity and intended claim release. |
+| `E_TASK_ABANDON_INCONSISTENT` | Explicit abandonment was refused because canonical ownership or append-only ledger evidence is inconsistent. | Repair and validate the task descriptor, recovery artifact, and ledger through their dedicated protocol paths before retrying. |
+| `E_TASK_ABANDON_INVALID_STATE` | The selected task is terminal or otherwise not eligible for explicit active-task abandonment. | Inspect task-show and next; only a valid non-terminal active task may be explicitly abandoned. |
+| `E_TASK_ABANDON_UNSAFE` | Task identity, lifecycle revision, ledger boundary, or claim ownership changed during explicit abandonment. | Re-inspect the task and retry only after the competing mutation has settled; never force claim release. |
+| `E_TASK_ALREADY_ABANDONED` | The task already has an active explicit-abandonment recovery boundary. | Inspect the existing recovery state; use task-resume only when explicit reacquisition is intended. |
 | `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_ALREADY_RECOVERED` | The task already has active durable recovered state. | Inspect the existing recovery metadata; use task-resume to reacquire claims or leave the task recovered. |
 | `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>. |
@@ -1458,3 +1733,23 @@ that order, satisfy any remaining gates, and require `READY` again.
 This recovery guidance is unavailable after execution has started, for an
 invalid ledger, or when the new route does not match the contract. Preserve
 those barriers and follow the task's canonical recovery guidance.
+
+## Gate Recording
+
+When `preflight` reports `E_GATE_UNVERIFIED`, use the executable command returned
+by `next` or record the required gate directly:
+
+```bash
+node src/cli.js gate-record \
+  --task <task-id> \
+  --gate threat-boundary \
+  --status satisfied \
+  --artifact THREAT_MODEL.md \
+  --decision "Threat boundary reviewed for this task" \
+  --json
+```
+
+ForgeLoop validates that the gate is required by the active route or policy,
+rejects traversal and symlink escapes, and computes artifact hashes itself.
+Changed referenced files produce `E_GATE_STALE`; manual gate JSON editing is not
+supported. Caller-recorded decisions are observations, not host attestation.

package/docs/UNIVERSAL_INTEGRATION.md

@@ -67,6 +67,31 @@ may be absent only when the canonical protocol marks it not applicable;
 presentation depth cannot change evidence, verification truth, authority,
 provenance, safety-floor, or validator-backed completion requirements.
 
+### Audit UX read model
+
+The read-only `task/audit-view` resource provides a bounded operator-facing
+projection of canonical status, audit, report, history, trace, ownership, next
+action, approvals, diagnostics, recovery, and completion data. It is suitable
+for timelines and audit panels, but it is not a lifecycle or evidence
+authority:
+
+```js
+const view = await readForgeLoopIntegrationResource("task/audit-view", {
+  taskId: "task-1",
+  limit: 50,
+  categories: ["LIFECYCLE", "CHECK", "DIAGNOSTIC"],
+});
+```
+
+Timeline items use deterministic sequence-backed IDs and explicit `null`
+timestamps when the ledger lacks an authoritative timestamp. `limit`,
+`beforeSequence`, `afterSequence`, and category filters are bounded. Raw event
+payloads, commands, environment values, credentials, absolute paths, and
+provider output are not exposed. Reading the resource performs no command,
+provider, artifact, claim, or lifecycle mutation. Use the canonical CLI/API
+commands for every state-changing operation. See [`AUDIT_UX.md`](./AUDIT_UX.md)
+for the complete projection contract.
+
 ### Repository Search boundary
 
 The Integration API exposes direct, transport-neutral repository operations:
@@ -183,6 +208,12 @@ there is no stock `context-recall` command. A consumer that only understands
 `canonicalHandoffs` v1 may disable only the handoff-specific UI while retaining
 the rest of Protocol v1 functionality.
 
+`advisoryContextProviders` v1 is the existing dedicated, lazy, opt-in
+Integration API capability. `providerExtensions` v1 is the broader experimental
+architecture vocabulary advertised by `protocol-info`. Generic provider
+registry injection is not public yet; do not add a generic `providers` field
+to `createForgeLoopContext()`.
+
 ## Consumers
 
 | Surface | Entry |

package/docs/assets/diagrams/forgeloop-code-attestation-flow.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en" data-theme="dark" data-preset="signal-flow" data-present="true">
 <head>
-      <meta name="forgeloop-diagram-source-sha256" content="33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb">
+      <meta name="forgeloop-diagram-source-sha256" content="eb8ca8fdfceb9e50cf7cd07be8622dcac127cfee80c8e2929d604c40138cc594">
     <meta name="forgeloop-diagram-renderer" content="archify@2.15.0 (e1ac748f19cf805e44bf74fb93c796662152e273)">
 <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
@@ -5432,7 +5432,7 @@
           <h3>Trust Levels</h3>
         </div>
         <ul>
-          <li>&bull; PROCESSED means artifacts exist and parse</li>
+          <li>&bull; PROCESSED is a minimum reported level; MISSING, DISABLED, and INVALID remain separate statuses</li>
           <li>&bull; VERIFIED means completion, evidence, manifest, and content bindings validate</li>
           <li>&bull; ATTESTED additionally requires a valid external signature policy</li>
           <li>&bull; No supplied CI receipt means NOT_VERIFIED, not a trust level</li>

package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json

@@ -15,16 +15,16 @@
     "license": "MIT"
   },
   "input": {
-    "sha256": "33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb",
-    "bytes": 9857
+    "sha256": "eb8ca8fdfceb9e50cf7cd07be8622dcac127cfee80c8e2929d604c40138cc594",
+    "bytes": 9910
   },
   "artifacts": {
     "html": {
-      "sha256": "85bb7abf910d3f6dd12037cfcd90c4b67f0aad4dca2b4cb21be1b0112cbdd92e",
-      "bytes": 653258
+      "sha256": "58f12b47996c7e901dadbf60988e0a8aa9b4af3687e3924129e87f62a9a13f89",
+      "bytes": 653311
     },
     "svg": {
-      "sha256": "3a768148886ffdfcce75221c11e51ee77a3702510e90917bf6e8ba0581ebdb44",
+      "sha256": "876c6400a34f9fe9773e61d968ddf773669cc14153933de2b2ceccd4386506a7",
       "bytes": 216543
     }
   },

package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg

@@ -1,4 +1,4 @@
-<svg data-archify-version="2.15.0" data-forgeloop-source-sha256="33bb9c3c4f3fb4a793febeab34b2d07ca7bf2c058d4f5e7575dba3a6065eedeb" data-theme="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 1024" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
+<svg data-archify-version="2.15.0" data-forgeloop-source-sha256="eb8ca8fdfceb9e50cf7cd07be8622dcac127cfee80c8e2929d604c40138cc594" data-theme="dark" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 1024" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase">
     <style>
       .c-bg-rect { fill: var(--bg); }
 /* Keep boundary labels clear of the first node in each group. */