@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/docs/RELEASE_CHECKLIST.md

@@ -3,10 +3,10 @@
 This is the current release checklist for `@cassiomc1/forgeloop`. It is a
 preparation and verification checklist; it does not authorize publication.
 
-## ForgeLoop 1.12.0 candidate scope
+## ForgeLoop 1.14.0 candidate scope
 
-The 1.12.0 candidate carries the first-class Flutter guide and deterministic,
-scope-aware project routing added by PR #165. The candidate must keep these
+The 1.14.0 candidate carries the protocol, routing, provider, documentation,
+and package changes present in current `main`. The candidate must keep these
 boundaries explicit:
 
 - [ ] README catalog and architecture fallback identify
@@ -47,7 +47,19 @@ actions.
 
 ## CI minimization validation
 
+- [ ] `npm run skill:check` passes and generated Skill frontmatter, protocol
+      synchronization, safety boundaries, and package coverage remain valid.
+
 - [ ] `npm run verify:fast` passes for edit-time feedback.
+- [ ] `npm run repository:hygiene` passes: no tracked mutable ForgeLoop state,
+      unexpected root reports, orphan visual assets, unapproved benchmark run
+      sets, or scratch outputs.
+- [ ] The documentation manifest and review matrix cover every maintained and
+      packaged document with origin, currency, package, action, and canonical
+      source metadata.
+- [ ] Diagram source, generated output, receipts, and review bindings are
+      current; a changed source is not approved until its visual review is
+      renewed.
 - [ ] `npm run verify:prepush` passes before the release pull request; MCP
       setup, when needed, was run explicitly with `npm run mcp:setup`.
 - [ ] Ordinary PR validation uses `.github/workflows/pr-core.yml` with the
@@ -86,7 +98,27 @@ actions.
 - [ ] `protocol-info` and the Integration API capability contracts agree.
 - [ ] `canonicalHandoffs` v2 is advertised consistently.
 - [ ] `advisoryContextProviders` v1 is advertised consistently.
+- [ ] `providerExtensions` v1 is consistent, provider-neutral, experimental,
+      and retains false lifecycle/completion/evidence authority.
+- [ ] Generic provider registry export remains absent and auto-install remains
+      false.
 - [ ] Advisory context remains Integration-API-only.
+- [ ] OpenSrc requires an explicit absolute executable path and lazily qualified expected version.
+- [ ] OpenSrc cache remains outside the target project and returned source paths are containment-validated.
+- [ ] OpenSrc recall remains advisory, non-evidence, and non-persisted by ForgeLoop.
+- [ ] No OpenSrc binary or cache ships in npm.
+- [ ] Optional Agent Browser uses a host-supplied absolute executable, has no
+      runtime dependency, and keeps browser observations non-authoritative.
+- [ ] Optional Emulated Services uses a host-supplied absolute `0.11.2`
+      executable, has no runtime dependency or PATH discovery, bounds argv
+      execution/readiness/output/cleanup, keeps state outside the target, and
+      returns observation-only loopback results.
+- [ ] Optional Security Review is host-injected through `securityReviewProviders`,
+      has no auto-install or scanner discovery, and keeps findings
+      observation-only, non-evidence, non-lifecycle, and non-completion.
+- [ ] Security Review request/result bounds, strict snapshot validation,
+      shared timeout, and cooperative cancellation are covered by focused tests
+      and the public TypeScript declarations.
 - [ ] `next`, `status`, and `task/context` invoke zero advisory providers.
 - [ ] Advisory request budgets are normalized before provider invocation.
 - [ ] Advisory results are never persisted by ForgeLoop.
@@ -97,8 +129,9 @@ actions.
 - [ ] Stale contract/route identity rejects handoff creation or acceptance.
 - [ ] An invalid event ledger projects `INCONSISTENT`.
 - [ ] Continuity lint remains non-authoritative and non-evidence.
-- [ ] `npm run dependency:policy` passes with only the approved exact runtime
-      parser dependency and approved development dependencies.
+- [ ] `npm run dependency:policy` passes with only the approved exact
+      `@typesafe-ai/sdk` and `smol-toml` runtime dependencies and approved
+      development dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.
 - [ ] `npm run benchmark:profiles:check` passes; absent provider/host history

package/docs/SECURITY_REVIEW.md

@@ -0,0 +1,71 @@
+# Security Review Provider
+
+The Security Review provider is an optional, host-injected Integration API
+capability for bounded, observation-only security findings. It is deliberately
+separate from ForgeLoop lifecycle, evidence, completion, claim, ownership,
+installation, command, and transaction authority.
+
+## Registration
+
+Register providers on `createForgeLoopContext({ securityReviewProviders })`.
+The registry accepts an object or `Map`, and each value is either a provider
+or a lazy factory. Registration validates provider identity but does not invoke
+factories, scan the project, start a process, access the network, install a
+tool, or mutate `.forgeloop` state.
+
+Provider IDs are lower-case portable identifiers. A provider must expose the
+same `id` as its registry key and a `review(request)` function. The host owns
+the provider implementation and any scanner or executable it uses; ForgeLoop
+does not discover tools or search `PATH`.
+
+## Invocation
+
+Call `runSecurityReview({ projectPath, taskId, providerName, reviewId, ... })`
+through `@cassiomc1/forgeloop/integration`. Requests are detached and deeply
+frozen before invocation. The request supports `FULL`, `CHANGED`, or
+`SELECTED` scope, bounded relative paths, categories, requirements, an
+optional revision binding, and a timeout capped by ForgeLoop.
+
+Factory resolution and `review()` share one deadline and one cooperative
+`AbortSignal`. A caller may provide its own signal. Timeout, cancellation,
+provider absence, invalid providers, malformed results, output limits, and
+provider failures have stable `E_SECURITY_REVIEW_*` error codes. Provider
+exceptions are normalized so provider code cannot spoof ForgeLoop errors.
+
+## Result contract
+
+Results are detached, deeply frozen JSON observations with bounded findings,
+diagnostics, and summary counts. The raw provider snapshot is also bounded
+before schema projection: nesting is limited to 32 levels, traversal to 4096
+nodes, and snapshot strings/keys to 524288 characters. Exceeding any bound
+fails closed with `E_SECURITY_REVIEW_OUTPUT_LIMIT`.
+
+Each finding has a portable relative path, bounded title/summary/rule/category/
+severity/confidence fields, and no secret-like content. For `SELECTED` scope,
+each finding path must equal or be a descendant of one of the requested paths;
+`CHANGED` applies the same rule when an explicit changed-path set is supplied.
+Containment uses normalized `/` separators and path-component boundaries, so
+`src/auth.js` does not authorize `src/authentication.js`. `FULL` scope has no
+requested-path restriction beyond normal safe-path validation. Results carry
+trust metadata stating that they are observation-only and non-evidence.
+
+Provider output is not a pass/fail lifecycle decision. It cannot create or
+modify contracts, routes, gates, events, transactions, receipts, claims,
+ownership, completion, executable commands, shell operations, credentials, or
+installation state. Any future use as canonical evidence requires a separate
+ForgeLoop-owned validation and evidence contract.
+
+## Operational rules
+
+- Keep registration lazy and explicit.
+- Use a host-owned provider and a bounded request.
+- Treat findings as advisory observations, not proof of `VALID`, `COMPLETE`,
+  or any lifecycle phase.
+- Handle timeout and cancellation cooperatively and clean up resources owned by
+  the provider.
+- Do not persist provider output as ForgeLoop task state unless a future
+  canonical evidence contract explicitly defines that boundary.
+
+See [`PROVIDER_ARCHITECTURE.md`](./PROVIDER_ARCHITECTURE.md),
+[`PROVIDERS.md`](./PROVIDERS.md), and [`THREAT_MODEL.md`](../THREAT_MODEL.md)
+for shared provider and security-boundary rules.

package/docs/SEMANTIC_DECISION_PLANE.md

@@ -0,0 +1,71 @@
+# Semantic Decision Plane
+
+ForgeLoop uses the pinned TypeSafe Jev model `jev-1.13.0` for bounded semantic decisions. The SDK version is exact-pinned in `package.json` and credentials are read only from `TYPESAFE_API_KEY`; credentials are never persisted in ForgeLoop artifacts, event details, diagnostics, or logs.
+
+Jev output has `SEMANTIC_DECISION` authority and `NONE` evidence authority. It cannot advance lifecycle, change ownership, satisfy gates, record verification, mark completion, install dependencies, execute commands, or delete tests. ForgeLoop remains the deterministic authority for state, claims, locks, schemas, event chronology, evidence, recovery, and completion.
+
+The decision registry contains versioned question sets for intake, contract
+applicability, route, execution profile, context, model routing, failure triage,
+diagnosis, review, task overlap, test utility, and test pruning. Current route,
+context, and test-utility mutations also use bounded dynamic candidate question
+sets: `route-candidates-v1`, `context-candidates-v1`, and
+`test-utility-candidates-v1`. Failure triage, diagnosis prioritization, and review planning
+remain advisory projections: deterministic mandatory review signals are always
+unioned into the plan, unknown semantic output escalates, and no projection can
+record evidence or authorize an action.
+
+Decision freshness separates canonical lifecycle state from semantic request
+state. Persisted artifacts retain both fingerprints and their combined request
+fingerprint, so lifecycle mutations cannot be mistaken for semantic changes
+and semantic changes cannot be hidden by a stable lifecycle revision. The
+lifecycle, event ledger, claims, and artifact validators remain authoritative.
+
+Test utility analysis uses the bounded `test-utility-candidates-v1` question set
+for the current command path; `test-utility-v1` remains a registered base
+question set. The analysis is persisted separately from
+completion evidence. Protected, contract-linked, public-API, security, and
+protocol tests remain keep-required or keep-risk-guard candidates; unknown
+utility is blocked and no command performs deletion.
+
+Context plans send bounded, sanitized actual candidates to Jev. The candidate-set
+fingerprint is bound to the persisted decision, and Jev returns candidate ranking
+and exclusion judgments consumed by the context compiler. Deterministic required
+and mandatory candidates remain selected; prompt-injection candidates are never
+given semantic authority. Token values are `UNKNOWN` unless the provider or host
+reports them.
+
+Route execution records intake, route relevance, and execution-profile decisions
+before persisting the route. The deterministic router remains the eligibility
+and safety floor; Jev may rank or exclude only eligible non-mandatory guides and
+may raise the execution profile, never lower a deterministic safety floor.
+Mandatory safety protection is derived from the canonical deterministic route
+reasons already produced by the router (`isMandatorySafetyGuide` reads the
+`MANDATORY_SAFETY_REASONS` set — `SURFACE_AUTH` plus the trust-boundary risk
+reasons `RISK_UNTRUSTED_INPUT`, `RISK_PERSONAL_DATA`, `RISK_SECRETS`,
+`RISK_EXTERNAL_SERVICE`, `RISK_PUBLICATION`), so a security guide selected for an
+external-service boundary cannot be removed by Jev and retains an explicit
+`MANDATORY_SAFETY_GUIDE` reason. Mandatory safety guides and low-confidence
+exclusions remain selected. A missing live decision fails closed.
+
+The semantic provider is injected into repository tests through an internal
+loader only. There is no production environment switch that turns semantic
+decisions into fixture results; packaged commands without the pinned provider
+fail closed.
+
+`npm run jev:smoke` performs only a tiny health request when credentials are configured. A missing credential reports `NOT_RUN`; an unavailable or rate-limited service is a failed live check, never a fabricated success. Provider failures are classified into stable error codes (authentication, unsupported model, rate limit, timeout, result normalization) and, for live maintainer diagnostics, the smoke result additionally reports only safe metadata (HTTP status, provider error type, request id, network class) — never credentials, headers, or raw request bodies. Inspection, recovery, and completion validation do not require a live Jev call, but a semantic-required mutation fails closed when its canonical decision is missing or stale.
+
+The `INTAKE` and `CONTRACT_APPLICABILITY` checkpoints are observation-only in
+this version. Their immutable decisions are recorded, fingerprinted, and
+available for review and follow-up consumption, but their result does not
+currently alter the route or create, skip, or weaken the contract: Jev never
+removes user or deterministic signals, and a semantic `applicable: false` can
+never suppress a deterministic contract requirement. A narrow additive consumer
+was evaluated and deferred because it changes behavior across every provider
+mode without a validated benefit; semantic consumption is tracked as a
+follow-up task, not claimed as current routing quality.
+
+Semantic-required operations use fail-closed cutover semantics: an unavailable,
+stale, malformed, or unsupported decision cannot silently authorize a mutation.
+Offline inspection, recovery, and deterministic completion validation remain
+usable without a live Jev request. Cached decisions may be used only when their
+existing fingerprint/freshness validators accept them.

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

@@ -12,6 +12,7 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [`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)
@@ -329,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`)
@@ -346,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.
@@ -361,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
@@ -487,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:
@@ -1232,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 -->
@@ -1298,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. |
@@ -1319,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. |
@@ -1350,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. |
@@ -1389,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. |
@@ -1467,6 +1631,14 @@ 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. |
@@ -1494,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>. |
@@ -1556,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>