@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/docs/CLI_REFERENCE.md

@@ -18,6 +18,275 @@ Commands that support structured machine-readable output document `--json` in th
 
 <!-- END FORGELOOP GENERATED: cli-common-options -->
 
+## Storage maintenance
+
+### `storage-migration-status`
+
+Inspects the bootstrap storage layout and retained maintenance ownership even
+when ordinary commands are excluded. It neither opens nor validates the
+database, removes an exclusion, nor proves that its owner is alive or dead.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migration-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit bootstrap storage layout and retained maintenance ownership
+
+<!-- END FORGELOOP GENERATED: cli:storage-migration-status:options -->
+
+### `storage-migration-resume`
+
+Requires externally excluded writers and the exact retained dead local owner UUID reported by `storage-migration-status`. Continues verified STAGED, ARCHIVING or ARCHIVED publication, or verifies PUBLISHED current state without restoration. Verified unpublished staging can be retained and rebuilt. Unrecorded capture, unbound candidate files and interrupted owner handoffs remain refused.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migration-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained migration directory relative to the project
+- `--expected-owner <uuid>`: exact retained maintenance owner reported by storage-migration-status
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped
+- `--reconcile-unbound-handoff`: preserve an unbound legacy handoff by atomic archival before resuming the exact dead owner
+- `--json`: emit recovery verification metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-migration-resume:options -->
+
+### `storage-rollback-resume`
+
+Resume a recorded source rollback publication under an exact dead local maintenance owner. Stop and exclude all writers; keep native writes excluded. The clean supported legacy target is validated before owner adoption. Actual source/native locations, captured bytes, independent backup and owner history are revalidated before operation journals change. Target validation must pass for every task before maintenance release.
+
+```bash
+forgeloop storage-rollback-resume --path <project> --destination <retained-migration> --expected-owner <uuid> --legacy-root <clean-supported-checkout> --writers-quiesced --native-writes-excluded --json
+```
+
+Recorded `PREPARING`/`READY` preparation and staging journals, and `SWITCHING`, `NATIVE_RETAINED` and `RESTORED` publication journals are supported. Incomplete staging copies are retained before rebuilding from verified captured source. Unrecorded directories, remote/live owners and ambiguous bytes are refused and retained for reconciliation. No deletion or replacement of retained source/native backups is authorized by failure.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-rollback-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--expected-owner <uuid>`: exact retained dead local owner reported by storage-migration-status
+- `--destination <path>`: retained migration with recorded rollback preparation, staging or publication
+- `--legacy-root <path>`: clean supported pinned legacy checkout used for actual target validation
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped and excluded
+- `--native-writes-excluded`: assert that native writes have been excluded since migration; snapshot equality alone does not prove this
+- `--json`: emit restoration and target-validation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-rollback-resume:options -->
+
+### `storage-rollback`
+
+Conditionally restore the preserved legacy source before any native writes have been accepted. Stop and exclude every writer, including old clients and background integrations. Inventory the clients and retain their exclusion throughout validation. Snapshot equality does not prove that no native writes occurred: `--native-writes-excluded` is an explicit operator assertion about the entire interval since migration. If native writes occurred, use a verified reverse export for the exact target version or forward repair instead.
+
+```bash
+forgeloop storage-rollback --path <project> --destination <retained-migration> --legacy-root <clean-supported-checkout> --writers-quiesced --native-writes-excluded --json
+```
+
+The supported validator checkout is the clean tracked Git commit `ee9ce11123d4e728d3dbc92f5d62d4bf41bb79c5`. Other target commits are refused. The command validates that target before acquiring maintenance, revalidates retained source and unchanged native authority, backs up native database and referenced attachment bytes, stages captured source, retains original native files by rename, and publishes exact source roots. It runs the pinned legacy CLI against every retained task and checks the task catalog before allowing maintenance release. The command executes Git and the explicitly supplied target CLI locally.
+
+Original native files, independent backups, captured source, inventories and validation receipts are retained. No automatic disposal occurs. On failure, keep all writers excluded and inspect maintenance owner and retained operation state. A failed attempt is not authorization to delete exclusion or retry over retained paths. Use `storage-rollback-resume` only for recorded preparation, staging or publication states. Unbound attempts remain refused; the original migration resume command must not be used to recover rollback operations.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-rollback:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained published migration directory relative to the project
+- `--legacy-root <path>`: clean supported pinned legacy checkout used for actual target validation
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped and excluded
+- `--native-writes-excluded`: assert that native writes have been excluded since migration; snapshot equality alone does not prove this
+- `--json`: emit restoration and target-validation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-rollback:options -->
+
+### `storage-migrate`
+
+Initial migration requires a new retained destination and externally stopped writers, including older clients. It validates and retains legacy sources, archives operational files, activates SQLite, and verifies current state. Failed attempts retain maintenance exclusion and evidence. Resume supports verified publication stages and identified unpublished staging; unrecorded capture and unbound candidate files remain refused.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migrate:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: new retained migration directory relative to the project; missing parent directories are created
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped
+- `--json`: emit migration publication and verification metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-migrate:options -->
+
+### `storage-restore-resume`
+
+Resumes restore after confirming that its exact retained local owner is dead. Requires externally excluded writers. Partial snapshots and prior rebuild intents are retained before rebuilding from verified source; completed preparation must pass source parity and domain validation. Conflicting intent records, unbound objects and changed preterminal databases remain refused. Terminal verification preserves accepted later work.
+
+```bash
+forgeloop storage-restore-resume --path /path/to/project --operation <restore-uuid> --expected-owner <owner-uuid> --writers-quiesced --json
+```
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-restore-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--operation <uuid>`: exact retained restore journal operation UUID
+- `--expected-owner <uuid>`: exact retained maintenance owner UUID
+- `--replace-active`: explicitly select active replacement with retained outgoing authority
+- `--writers-quiesced`: assert that all writers have been externally stopped
+- `--json`: emit restore recovery metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-restore-resume:options -->
+
+### `storage-restore`
+
+Restores an attachment-inclusive backup into a project with no existing operational state. Requires explicit exclusion of all writers. Retains an independent snapshot and restore journal; failed operations keep maintenance exclusion. Active-project replacement is not supported yet.
+
+```bash
+forgeloop storage-restore --path /path/to/fresh-project --source /path/to/verified-backup --writers-quiesced --json
+```
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-restore:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--source <path>`: verified attachment-inclusive backup directory; absolute or relative to the target project
+- `--replace-active`: explicitly select active replacement with retained outgoing authority
+- `--writers-quiesced`: assert that all writers have been externally stopped
+- `--json`: emit restore activation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-restore:options -->
+
+### `storage-backup`
+
+Creates a database-only backup of an existing canonical SQLite project. The
+destination is relative to the project, its parent must exist, and an existing
+destination is never replaced. External attachments are not included.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-backup:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: new backup file or attachment-inclusive directory relative to the project; parent directory must exist
+- `--include-attachments`: create a new backup directory including all canonically referenced attachment bytes
+- `--json`: emit backup metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-backup: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 +327,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) |
+| **Setup & Maintenance** | [`storage-restore-resume`](#storage-restore-resume), [`storage-restore`](#storage-restore), [`storage-migration-status`](#storage-migration-status), [`storage-migration-resume`](#storage-migration-resume), [`storage-rollback`](#storage-rollback), [`storage-rollback-resume`](#storage-rollback-resume), [`storage-migrate`](#storage-migrate), [`storage-backup`](#storage-backup), [`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) |
+| **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) |
 | **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) |
@@ -755,7 +1024,7 @@ Reports the public compatibility handshake required by external ForgeLoop harnes
 
 - **Example**:
 
-  <!-- FORGELOOP EXAMPLE: cli-reference:protocol-info | exit=0 | json.commands.0.name=protocol-info -->
+  <!-- FORGELOOP EXAMPLE: cli-reference:protocol-info | exit=0 | json.protocolVersion=1 | json.features.operationalStorage.sqlite.format=sqlite -->
   ```bash
   forgeloop protocol-info --json
   ```
@@ -767,7 +1036,7 @@ Initializes ForgeLoop in a target repository.
 
 - **Purpose**: Installs canonical instruction templates under `.forgeloop/kit/`, creates discovery shims at root, and prepares `.forgeloop/`.
 - **When to use**: Once when onboarding a new repository to ForgeLoop.
-- **Mutation**: Writes `.forgeloop/kit/`, `.forgeloop/forgeloop.gitignore`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`.
+- **Mutation**: Writes `.forgeloop/kit/`, `.forgeloop/.gitignore`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:init:options -->
@@ -834,6 +1103,107 @@ 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.
@@ -1967,6 +2337,31 @@ 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`
@@ -1974,9 +2369,9 @@ Clears canonical work-state checkpoint for the current task.
 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, 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 also needs authorized completion recovery.
+- **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 artifact drift, invalid ledgers, unknown requirements, and failing evidence.
+- **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 -->
@@ -2155,6 +2550,8 @@ Migrates a legacy 1.0 single-task `.forgeloop/` layout into a namespaced task di
 <!-- BEGIN FORGELOOP GENERATED: cli:task-migrate:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained source and publication evidence destination
+- `--writers-quiesced`: confirm all legacy writers are stopped and excluded
 - `--dry-run`: show planned migration actions without moving files
 - `--json`: emit structured output as JSON
 
@@ -2185,6 +2582,8 @@ protocol version.
 <!-- BEGIN FORGELOOP GENERATED: cli:migrate-protocol:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained source and publication evidence destination
+- `--writers-quiesced`: confirm all legacy writers are stopped and excluded
 - `--to <protocolVersion>`: target supported protocol version
 - `--dry-run`: show migration actions without writing or deleting artifacts
 - `--json`: emit structured migration result as JSON
@@ -2251,6 +2650,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