@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/docs/BROWSER_VERIFICATION.md

@@ -0,0 +1,136 @@
+# Browser Verification
+
+## Status
+
+Browser verification is a provider-neutral, host-injected v1 observation
+contract. It is experimental and explicit. ForgeLoop does not select a browser
+vendor, install a browser, or invoke verification from lifecycle commands.
+
+## Purpose and Architecture
+
+`runBrowserVerification` validates a bounded request, resolves one registered
+provider, and turns its untrusted observation into an immutable result. Core
+does not perform browser I/O. The runtime registry is inert at context
+construction; factories are lazy and are invoked only by the explicit API call.
+
+## Invocation
+
+Provide an explicit task, target, requirement, and verification identity along
+with `runtimeContext.browserVerificationProviders`:
+
+```js
+const result = await runBrowserVerification({
+  taskId: "task-123",
+  target: "/workspace/project",
+  providerName: "playwright",
+  verificationId: "checkout",
+  requirement: "Checkout is usable",
+  startUrl: "https://app.example.test/checkout",
+  allowedOrigins: ["https://app.example.test"],
+  steps: [{ id: "open", kind: "NAVIGATE", url: "https://app.example.test/checkout" }],
+  assertions: [{ id: "title", kind: "TITLE_EQUALS", expected: "Checkout" }],
+  runtimeContext: { browserVerificationProviders: { playwright: provider } },
+});
+```
+
+Providers are registered by ID and must expose `verify(input)`. Factories are
+lazy and are resolved only when the explicit invocation runs. Provider input
+contains the normalized request, `signal`, and remaining `timeoutMs`. The
+`AbortSignal` is an invocation control, not protocol state.
+
+## Request Model
+
+Requests require `taskId`, `target` (or `projectPath`), `verificationId`,
+`requirement`, `startUrl`, `allowedOrigins`, at least one bounded step, and at
+least one bounded assertion. Optional viewport, screenshot capture policy, and
+timeout values are bounded. Unknown request, step, locator, assertion, capture,
+or viewport fields are rejected. Arbitrary scripts, headers, cookies, uploads,
+downloads, shell commands, and executable paths are not part of this contract.
+
+Supported steps are `NAVIGATE`, `CLICK`, `FILL`, `PRESS`, and `WAIT_FOR`.
+Supported assertions include visibility, text, value, attribute, URL, title,
+and their documented bounded variants. Assertion results must match the
+requested IDs, kinds, cardinality, and order exactly.
+
+`WAIT_FOR` is strict: visibility, hidden-state, and text waits require a
+locator; text and URL waits require an expected value, and URL wait values must
+also be in the exact origin allowlist.
+
+## Origins and Navigation
+
+Authored URLs and provider-reported `finalUrl` and `navigations` must use
+`http:` or `https:`, contain no credentials, and have an exact origin in
+`allowedOrigins`. Hostnames are case-normalized and trailing-dot hostnames are
+rejected. `localhost` and IPv4 origins are supported; bracketed IPv6 literals
+are intentionally excluded in v1. The allowlist is an observation policy, not
+a network sandbox: providers remain responsible for browser network access.
+
+## Result Model
+
+The normalized result contains task and requirement binding, provider identity,
+assertions, final navigation state, diagnostics, optional accessibility
+snapshots, and structured screenshot metadata. Raw image bytes are never
+returned. Artifact references are portable, bounded, credential-free metadata
+with a lowercase SHA-256 digest.
+
+ForgeLoop derives overall status: any `FAIL` assertion yields `FAIL`, otherwise
+any `BLOCKED` yields `BLOCKED`, otherwise all assertions yield `PASS`. A raw
+provider status is optional and, when present, must match that derived value.
+Provider output cannot choose lifecycle state, evidence, completion, claims, or
+next actions. Unknown top-level fields and authority-bearing fields fail closed.
+
+Snapshots are optional explicit `ACCESSIBILITY` observations with bounded
+portable text. They are never assertion status or authority.
+
+## Timeout and Cancellation
+
+Factory resolution, provider validation, provider verification, and result
+normalization share one ForgeLoop-owned deadline. On expiry ForgeLoop aborts
+the shared signal, allows only bounded cooperative cleanup, and returns
+`E_BROWSER_VERIFICATION_TIMEOUT`. Late provider resolution cannot change the
+returned result. Providers must observe the signal and clean up resources they
+own; synchronous JavaScript cannot be forcibly preempted.
+
+## Trust Boundary and Credentials
+
+Provider output is untrusted and normalized under strict size limits. Results
+are stamped with `authority: "OBSERVATION"`, `evidenceAuthority: "NONE"`,
+`actionability: "NON_EXECUTABLE"`, `lifecycleAuthority: false`, and
+`completionAuthority: false`. Provider output cannot substitute for ForgeLoop
+validation or lifecycle evidence.
+
+Provider errors are mapped to generic, secret-safe public errors. Raw causes,
+stacks, stderr, cookies, tokens, signed URLs, and local paths are not public
+metadata. Credentials must not be placed in requests, URLs, artifacts,
+diagnostics, or snapshots.
+
+## Evidence Boundary
+
+Results are observation-only: `persisted: false`, `evidenceAuthority: "NONE"`,
+`completionAuthority: false`, and `evidenceRequiresForgeLoopValidation: true`.
+Running this API does not mutate tasks, claims, routes, contracts, events,
+receipts, checks, evidence, recovery, or actions.
+
+## Network and Session Semantics
+
+The origin allowlist does not provide browser isolation or prevent provider
+network access. Providers own browser sessions and must not reuse credentials
+or session state across unrelated invocations. No automatic browser install,
+executable discovery, browser adapter, or auto-invocation is provided.
+
+## Future Adapters and Troubleshooting
+
+The optional Agent Browser adapter implements this provider contract through
+`createAgentBrowserVerificationProvider`. It requires a host-supplied absolute
+executable and never installs Agent Browser or Chrome. No vendor is canonical,
+and no lifecycle command invokes the adapter. See
+[`AGENT_BROWSER_ADAPTER.md`](./AGENT_BROWSER_ADAPTER.md) for its process,
+session, screenshot, and troubleshooting boundaries. For malformed requests,
+invalid results, origin escapes, provider failures, and timeouts, use the
+stable error codes in `docs/TROUBLESHOOTING.md`.
+
+## Compatibility
+
+The canonical public operation is `runBrowserVerification`. The runtime
+registration key remains `browserVerificationProviders`, and the provider kind
+remains `BROWSER_VERIFICATION`.

package/docs/CLI_REFERENCE.md

@@ -18,6 +18,135 @@ Commands that support structured machine-readable output document `--json` in th
 
 <!-- END FORGELOOP GENERATED: cli-common-options -->
 
+## Semantic decision projections
+
+### `decision-status`
+
+Reports the pinned Jev configuration and, only when explicitly requested,
+performs a bounded provider health check.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:decision-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--health`: perform a bounded live Jev health check when credentials are configured
+- `--json`: emit decision-plane status as JSON
+
+<!-- END FORGELOOP GENERATED: cli:decision-status:options -->
+
+### `decision-show`
+
+Shows a persisted semantic decision without performing a live request.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:decision-show:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--decision <id>`: decision artifact ID
+- `--json`: emit the decision artifact as JSON
+
+<!-- END FORGELOOP GENERATED: cli:decision-show:options -->
+
+### `context-plan`
+
+Compiles a bounded, non-authoritative context plan.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:context-plan:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--decision <id>`: persisted Jev decision artifact ID
+- `--profile <profile>`: bounded context budget profile
+- `--json`: emit the bounded context plan as JSON
+
+<!-- END FORGELOOP GENERATED: cli:context-plan:options -->
+
+### `model-route`
+
+Projects the deterministic model-routing floor. Jev may escalate but cannot
+lower the floor or select vendor-specific models.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:model-route:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--decision <id>`: persisted Jev decision artifact ID
+- `--work <type>`: declared work type
+- `--surface <value>`: affected surface (repeatable)
+- `--risk <value>`: task risk (repeatable)
+- `--platform <value>`: affected platform (repeatable)
+- `--behavior-change`: declare behavior change
+- `--executable-change`: declare executable/configuration change
+- `--generation-required`: declare that generation is required
+- `--architecture-change`: declare an architectural change
+- `--ambiguous`: declare unresolved ambiguity
+- `--json`: emit model-route projection as JSON
+
+<!-- END FORGELOOP GENERATED: cli:model-route:options -->
+
+### `semantic-plan`
+
+Projects bounded failure, diagnosis, or review planning from ForgeLoop-owned
+question-set categories.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:semantic-plan:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--decision <id>`: persisted Jev decision artifact ID
+- `--kind <failure|diagnosis|review>`: bounded semantic planning projection
+- `--input <json>`: bounded failure, diagnosis, or review context
+- `--json`: emit semantic plan projection as JSON
+
+<!-- END FORGELOOP GENERATED: cli:semantic-plan:options -->
+
+### `test-inventory`
+
+Discovers deterministic test units and stable test IDs.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:test-inventory:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit deterministic test inventory as JSON
+
+<!-- END FORGELOOP GENERATED: cli:test-inventory:options -->
+
+### `test-utility`
+
+Persists non-evidence test utility analysis. It never removes tests.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:test-utility:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit test utility analysis as JSON
+
+<!-- END FORGELOOP GENERATED: cli:test-utility:options -->
+
+### `test-prune-plan`
+
+Projects a safe non-destructive test pruning plan.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:test-prune-plan:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit test prune plan as JSON
+
+<!-- END FORGELOOP GENERATED: cli:test-prune-plan:options -->
+
+### `test-prune-probe`
+
+Probes only eligible candidates in isolation and never modifies the live tree.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:test-prune-probe:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--test <id>`: stable test ID to probe in isolation
+- `--json`: emit test prune probe as JSON
+
+<!-- END FORGELOOP GENERATED: cli:test-prune-probe:options -->
+
 ---
 
 ## CLI Syntax Contract
@@ -58,10 +187,10 @@ error codes. Default output and default JSON remain unchanged.
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Setup & Maintenance** | [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
-| **Verification & Completion** | [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`decision-status`](#decision-status), [`decision-show`](#decision-show), [`context-plan`](#context-plan), [`model-route`](#model-route), [`semantic-plan`](#semantic-plan), [`test-inventory`](#test-inventory), [`test-utility`](#test-utility), [`test-prune-plan`](#test-prune-plan), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Verification & Completion** | [`test-prune-probe`](#test-prune-probe), [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
+| **Lifecycle & State** | [`discover`](#discover), [`contract-create`](#contract-create), [`gate-record`](#gate-record), [`gate-revalidate`](#gate-revalidate), [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
+| **Setup & Maintenance** | [`contract-revise`](#contract-revise), [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`checkpoint-revalidate`](#checkpoint-revalidate), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-abandon`](#task-abandon), [`task-repair-contract-bootstrap`](#task-repair-contract-bootstrap), [`task-migrate-contract-bootstrap-repair`](#task-migrate-contract-bootstrap-repair), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
 | **Durable Actions & Approvals** | [`run-action`](#run-action), [`action-propose`](#action-propose), [`action-record`](#action-record), [`action-show`](#action-show), [`action-reconcile`](#action-reconcile), [`action-verify`](#action-verify), [`action-authorize`](#action-authorize), [`approval-request`](#approval-request), [`approval-resolve`](#approval-resolve) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
@@ -834,11 +963,112 @@ Updates the managed instruction kit to match the current ForgeLoop package versi
 
 ## 2. Activation & Planning
 
+### `discover`
+
+Records the canonical initial discovery milestone for a newly created task.
+
+- **Purpose**: Transitions a valid post-`task-create` task from `RECEIVED` to the derived `DISCOVERING` phase without creating synthetic work state.
+- **When to use**: When `next` returns `DISCOVER` for a task with no work-state checkpoint.
+- **Mutation**: Appends the task-scoped discovery milestone to the event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:discover:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured discovery output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:discover:options -->
+
+### `contract-create`
+
+Persists a validated contract and materializes the first real lifecycle checkpoint.
+
+- **Purpose**: Creates a real contract after discovery and writes `work-state.json` with its actual contract fingerprint.
+- **When to use**: When `next` returns `CREATE_CONTRACT` after discovery.
+- **Mutation**: Writes the task contract, task work state, and append-only lifecycle events transactionally.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:contract-create:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--contract-file <path>`: validated JSON contract relative to the target
+- `--preset <name>`: bounded contract preset: documentation, bug, feature, or release
+- `--json`: emit structured contract output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:contract-create:options -->
+
+### `contract-revise`
+
+Replaces a validated pre-execution contract through an append-only, transaction-witnessed revision.
+
+- **Purpose**: Canonically revise a contract in `CONTRACT_READY`, `ROUTED`, or `PLANNED` before execution starts.
+- **When to use**: When the task objective or scope changes and the existing derived route, preflight, gates, or plan must no longer authorize the work.
+- **Mutation**: Writes the replacement contract, resets derived authorization, appends `CONTRACT_REVISED`, and appends an adjacent `TRANSACTION_COMMITTED(operation=contract-revise)` witness.
+- **Restrictions**: Requires exactly one of `--preset` or `--contract-file`; a `PLANNED` task rewinds to `ROUTED`, and old route/preflight/plan evidence must be regenerated.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:contract-revise:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--contract-file <path>`: validated replacement JSON contract relative to the target
+- `--preset <name>`: bounded replacement contract preset: documentation, bug, feature, or release
+- `--json`: emit structured contract revision output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:contract-revise:options -->
+
+### `gate-record`
+
+Records a gate satisfaction or rejection decision for a task's preflight gate lifecycle.
+
+- **Purpose**: Records structured evidence that a named gate has been satisfied, rejected, or deferred, with optional artifact and decision evidence.
+- **When to use**: During the preflight gate lifecycle to progress gate status from pending to resolved.
+- **Mutation**: Writes a gate artifact under the task namespace and appends a `GATE_SATISFIED` or `GATE_REJECTED` protocol event. A `GATE_SATISFIED` event after `CONTRACT_REVISED` must be immediately followed by the canonical `TRANSACTION_COMMITTED(operation=gate-record)` witness; pre-revision historical gate events remain backward compatible. Repeated satisfied recording is event-idempotent within the current contract epoch, even if the gate artifact is refreshed.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:gate-record:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--gate <name>`: required gate name
+- `--status <status>`: satisfied, unverified, or blocked
+- `--artifact <path>`: project-relative evidence artifact (repeatable)
+- `--decision <text>`: caller-recorded gate decision (repeatable)
+- `--unknown <text>`: known unresolved item (repeatable)
+- `--assumption <text>`: approved local assumption (repeatable)
+- `--evidence-file <path>`: bounded local descriptive evidence JSON
+- `--json`: emit structured gate output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:gate-record:options -->
+
+### `gate-revalidate`
+
+Refreshes a satisfied gate whose evidence artifacts changed after execution
+started, while preserving the original approval and append-only history.
+
+- **Purpose**: Revalidate stale gate artifacts only through current task identity and active write claims.
+- **When to use**: When `next` returns `REVALIDATE_GATES` for a post-execution task.
+- **Mutation**: Refreshes the task-scoped gate artifact and appends `GATE_REVALIDATED` with an adjacent `TRANSACTION_COMMITTED(operation=gate-revalidate)` witness.
+- **Restrictions**: Does not bypass `gate-record`'s `E_PHASE_FREEZE`; requires `--acknowledge-stale`, a coherent current route, and changed artifacts covered by active claims.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:gate-revalidate:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--gate <name>`: satisfied gate to refresh after safe artifact drift
+- `--acknowledge-stale`: explicitly acknowledge refresh of stale gate artifacts inside active task claims
+- `--json`: emit structured gate revalidation output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:gate-revalidate:options -->
+
 ### `route`
 
 Calculates and persists deterministic engineering guide routing.
 
-- **Purpose**: Selects relevant technical guides (e.g. `clean`, `test`, `security`, `design`) from declared work attributes and bounded structural project evidence such as an affected Flutter SDK dependency.
+- **Purpose**: Selects relevant technical guides (e.g. `clean`, `test`, `security`, `design`) from declared work attributes and bounded structural project evidence such as an affected Flutter SDK dependency, supported .NET project, confirmed Node.js backend runtime, valid Rust Cargo package/workspace, recognized C/C++, Java, Go, TypeScript, PHP, or Swift project, or owned SQL artifact. ASP.NET Core and ABP are conditional reasons on the `dotnet` specialist, not standalone guides; SQL is a host-project overlay.
 - **When to use**: During discovery before preflight.
 - **Mutation**: Writes `.forgeloop/task-state/<taskKey>/routing-result.json`.
 - **Options**:
@@ -982,6 +1212,7 @@ Computes the deterministic next action required by the protocol.
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
 - `--compact`: emit a bounded next-action projection
+- `--explain`: include bounded read-only blocker and recovery explanation
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:next:options -->
@@ -1966,16 +2197,41 @@ Clears canonical work-state checkpoint for the current task.
   forgeloop clear-state
   ```
 
+### `checkpoint-revalidate`
+
+Revalidates a safe pre-execution `ROUTED` checkpoint after repository-only
+drift.
+
+- **Purpose**: Rebinds the checkpoint to ForgeLoop's current repository fingerprint while preserving lifecycle, contract, route, guide, gate, check, and evidence identity.
+- **When to use**: When `next` returns `REVALIDATE_CHECKPOINT` with only `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED`.
+- **Mutation**: Advances the state revision and appends a transaction-bound `CHECKPOINT_REVALIDATED` event.
+- **Safety Note**: It does not accept caller-supplied repository identity, revise contracts, reroute, fabricate evidence, or operate after execution starts. Unsupported drift fails closed with `E_CHECKPOINT_REVALIDATION_UNSAFE`.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:checkpoint-revalidate:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured revalidation output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:checkpoint-revalidate:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop checkpoint-revalidate --task <id> --json
+  ```
+
 ---
 
 ### `reconcile-closure`
 
-Reconciles the checkpoint of an EXECUTING task whose objective is already satisfied in the current repository.
+Reconciles the checkpoint of an EXECUTING, VERIFYING, or REVIEWING task whose objective is already satisfied in the current repository.
 
-- **Purpose**: Refresh the work-state repository fingerprint of a stale EXECUTING task after repository movement, using executed contract-bound evidence that the objective is present, so the canonical completion pipeline can close it.
-- **When to use**: When a task is stuck in EXECUTING with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED` and its objective was already satisfied by other changes in the current repository.
-- **Mutation**: Appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus evidence) and refreshes the work-state repository fingerprint. Phase stays EXECUTING; claims release only through canonical `COMPLETE`.
-- **Safety Note**: Refuses non-EXECUTING tasks, fresh checkpoints, contract or artifact drift, invalid ledgers, unknown requirements, and failing evidence.
+- **Purpose**: Refresh the work-state repository fingerprint of a stale EXECUTING, VERIFYING, or REVIEWING task after repository movement, using executed contract-bound evidence that the objective is present, so the canonical completion pipeline can close it.
+- **When to use**: When a task is stuck in EXECUTING, VERIFYING, or REVIEWING with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED` and its objective was already satisfied by other changes in the current repository. A REVIEWING task may use an existing authorized completion-recovery snapshot, or the narrow bootstrap path when the only drift is repository movement and no completion rejection has been persisted.
+- **Mutation**: Appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus evidence) and refreshes the work-state repository fingerprint. The phase stays unchanged until the canonical pipeline advances it; claims release only through canonical `COMPLETE`.
+- **Safety Note**: Refuses other phases, fresh checkpoints, contract or required-artifact drift, invalid ledgers, invalid claim ownership, unauthorized persisted completion rejection, unknown requirements, and failing evidence. It never appends completion events or releases claims.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:reconcile-closure:options -->
@@ -2016,6 +2272,8 @@ Initializes a new isolated task namespace with write claims and contract.
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
 - `--claim <path>`: scoped file path or directory prefix claimed for mutation (repeatable)
 - `--contract-file <path>`: path to initial contract file
+- `--preset <name>`: bounded contract preset: documentation, bug, feature, or release
+- `--preview`: preview the contract without creating lifecycle state
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-create:options -->
@@ -2034,6 +2292,12 @@ Initializes a new isolated task namespace with write claims and contract.
 
   `--contract-file` points to a contract JSON that is validated and copied into the task namespace.
 
+  Use `--preset documentation|bug|feature|release --preview` for a bounded,
+  read-only contract proposal. Preview validates claims and creates no task
+  namespace or project-claims lock; repeat without `--preview` after reviewing
+  the proposal. Presets record unresolved decisions when concrete deliverables
+  are not supplied and do not publish or deploy release artifacts.
+
 ### `task-list`
 
 Lists all tasks discovered in `.forgeloop/task-state/`.
@@ -2045,14 +2309,27 @@ Lists all tasks discovered in `.forgeloop/task-state/`.
 <!-- BEGIN FORGELOOP GENERATED: cli:task-list:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--phase <phase>`: only return tasks in this lifecycle phase
+- `--active`: only return healthy tasks with active ownership and a non-terminal phase
+- `--limit <number>`: maximum tasks to return
+- `--offset <number>`: number of sorted tasks to skip
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:task-list:options -->
 
+  Results are sorted by task ID. `--phase` and `--active` filter the
+  presentation only; ownership and corruption checks still run for every
+  discovered task before filtering. `--limit` and `--offset` provide bounded
+  pagination and return `total` and `hasMore` in JSON. Listing never removes
+  ledger or recovery evidence. Discovery itself is exhaustive for valid task
+  namespaces because ownership and conflict correctness must not depend on a
+  page limit.
+
 - **Example**:
 
   ```bash
   forgeloop task-list --json
+  forgeloop task-list --active --limit 20 --offset 0 --json
   ```
 
 ### `task-show`
@@ -2229,6 +2506,111 @@ Fake, missing, corrupt, or mismatched recovery state is
 `E_TASK_CLAIM_OWNERSHIP_INCONSISTENT`/`E_TASK_RECOVERY_INCONSISTENT`; historical
 claims remain reserved.
 
+### `task-abandon`
+
+Explicitly abandons an active non-terminal task without fabricating completion.
+
+- **Purpose**: Releases validated write claims for a deliberately abandoned task while preserving its current lifecycle phase, append-only history, and durable recovery boundary. This is the canonical escape from an active-task claim deadlock; it is not a completion or publication operation.
+- **When to use**: Only when the exact task ID is known and the caller has deliberately acknowledged abandonment. Use `task-recover` only for tasks already classified `STALE` or `ABANDONED`.
+- **Mutation**: Appends `TASK_ABANDONED` and its `TRANSACTION_COMMITTED(operation=task-abandon)` witness, then writes `recovery.json` with classification `ABANDONED` and authority `CALLER_ACKNOWLEDGED`. Work state remains unchanged and claims resolve to `RELEASED_BY_RECOVERY`.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-abandon:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-abandonment`: explicitly acknowledge abandonment of an active task (required; not completion authority)
+- `--json`: emit structured abandonment output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-abandon:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-abandon --task task-001 --acknowledge-abandonment --json
+  ```
+
+The command requires an explicit task ID and acknowledgement. It refuses
+`COMPLETE`, already recovered, inconsistent, or non-active ownership states
+and never writes `COMPLETION_VALIDATED`. Use `task-resume` to reacquire claims
+through the normal lifecycle when work should continue.
+
+### `task-repair-contract-bootstrap`
+
+Repairs only the exact historical duplicate contract bootstrap defect.
+
+- **Purpose**: Recognizes the narrow append-only signature of a duplicate `CONTRACT_VALIDATED` followed by a duplicate `contract-create` commit, verifies the current contract and route/state bindings, and reconstructs the earliest proven checkpoint without rewriting existing events.
+- **Mutation**: Under project/task serialization, writes the reconciled work-state and appends `CONTRACT_BOOTSTRAP_REPAIR_RECORDED` plus `TRANSACTION_COMMITTED` in one transaction.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-repair-contract-bootstrap:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-repair`: explicit caller acknowledgement of the exact append-only repair (required)
+- `--json`: emit structured repair output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-repair-contract-bootstrap:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-repair-contract-bootstrap --task task-001 --acknowledge-repair --json
+  ```
+
+The command requires fresh caller acknowledgement. The marker records the
+repair-time checkpoint as an immutable anchor, including `reconstructedPhase`,
+`reconstructedStateFingerprint`, `reconstructedStateRevision`, and the
+repair-time `routeFingerprint`; it does not freeze the task at that checkpoint.
+The marker must be immediately followed by its
+`TRANSACTION_COMMITTED(operation=task-repair-contract-bootstrap)` witness.
+After the anchor revision, normal canonical lifecycle evolution is allowed, but
+state rollback, missing state, invalid current contract/route identity, or
+ledger/state incoherence fails closed with `E_CONTRACT_BOOTSTRAP_REPAIR_INVALID`.
+If a later route fingerprint differs from the marker, the current route and
+state must be canonically coherent and the ledger must contain a ForgeLoop-
+generated `ROUTE_REBOUND` witness immediately followed by the matching
+`TRANSACTION_COMMITTED(operation=route)`. The witness binds the current route
+fingerprint, the repair-time contract fingerprint, and the previous route
+fingerprint; a historical route transaction, or route and state fields changed
+together without this identity witness, is not authorization. A contract-only
+repair may establish its first route through canonical `runRoute`, recording a
+null previous route fingerprint. A proven `ROUTE_VALIDATED` milestone also
+requires a present, valid route artifact bound to the current contract, while a
+history without `ROUTE_VALIDATED` may repair to `CONTRACT_READY` without a
+route artifact. After repair, entering `DESIGNING` additionally requires the
+canonical `DESIGN_GATE_STARTED` event.
+
+### `task-migrate-contract-bootstrap-repair`
+
+Migrates the exact legacy contract bootstrap repair marker produced before
+`reconstructedStateRevision` was required.
+
+- **Purpose**: Proves the legacy marker, its immediate repair transaction, the current contract, the reconstructed work-state, and (for `ROUTED`) the persisted route. Strict validation remains fail-closed until the migration witness is appended.
+- **Mutation**: Appends `CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_RECORDED` plus `TRANSACTION_COMMITTED(operation=task-migrate-contract-bootstrap-repair)`; it never rewrites the legacy marker or state/contract/route artifacts.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:task-migrate-contract-bootstrap-repair:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--acknowledge-migration`: fresh explicit caller acknowledgement of the exact legacy marker migration (required)
+- `--json`: emit structured migration output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:task-migrate-contract-bootstrap-repair:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop task-migrate-contract-bootstrap-repair --task task-001 --acknowledge-migration --json
+  ```
+
+Only the exact legacy schema and immediate repair boundary are eligible. Any
+near-miss, later lifecycle activity, state/route drift, live lock, unknown lock,
+or corrupt lock fails closed with
+`E_CONTRACT_BOOTSTRAP_REPAIR_MIGRATION_INVALID`/`E_TASK_LOCKED`. The operation
+is idempotent only when the complete migrated relationship remains valid.
+
 ### `task-resume`
 
 Reacquires a recovered task's write claims and restores ordinary mutation authority.

package/docs/CODE_ATTESTATION.md

@@ -9,11 +9,11 @@ bug-free or secure.
 
 | Level | Meaning |
 | --- | --- |
-| `PROCESSED` | Protocol artifacts exist but verification is not complete. |
+| `PROCESSED` | Minimum reported level; verification is not complete. `MISSING`, `DISABLED`, and `INVALID` remain separate status results. |
 | `VERIFIED` | Completion, evidence bindings, manifest, and current content validate. |
 | `ATTESTED` | `VERIFIED` plus a cryptographically valid signature and trusted signer policy. |
 
-`PROCESSED` is an existence/parsing result, not a trust claim. A manifest or
+`PROCESSED` is a lower-bound reported level, not a trust claim. A manifest or
 statement that merely exists never becomes `ATTESTED`; the signature must be
 verified against the configured signer identity, issuer, and trust policy.
 Attestation binds bounded source/evidence relationships. It does not prove