@cassiomc1/forgeloop 1.13.0 → 1.14.0

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,6 +963,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 +2197,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 +2229,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 -->
@@ -2251,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

package/docs/DOCUMENTATION_GUIDE.md

@@ -54,11 +54,30 @@ Documentation-impact questions for integration/MCP changes:
 - Did an adapter error code change?
 - Did an integration limit or resource list change?
 
-Anti-drift invariant: every `documentation-manifest.json` entry marked
-`packaged: true` is mechanically checked against the core npm tarball
-contents (`tests/package.test.js`).
-
-Canonical phase and transition inventories must be derived from `WORK_PHASES`
+Anti-drift invariant: every packaged Markdown or harness-adapter document in
+`package.json.files` is registered in `documentation-manifest.json`, and every
+`packaged: true` manifest entry is mechanically checked against the core npm
+tarball contents (`tests/package.test.js`). The review matrix records generated
+or handwritten origin, current or historical status, package inclusion, action,
+and canonical sources for every registered document.
+
+### Documentation retention and repository hygiene
+
+Use one canonical owner for each maintained concept. Generated documentation
+must name its source, generator, freshness check, and reason for being tracked.
+Historical audits, release evidence, and completed validation records belong
+under `docs/history/`; current operating instructions must not leave those
+records loose in the repository root. One-off plans and validation reports are
+either consolidated into a canonical document and deleted or moved to the
+history index with their current owner links.
+
+Repository and npm decisions are separate. GitHub may retain reproducible
+benchmarks, PoC evidence, source-bound diagram artifacts, vendored renderer
+sources, and historical records that consumers do not need. The npm package
+ships only intentional runtime, integration, legal, harness, and canonical user
+documentation surfaces. `npm run repository:hygiene` enforces explicit root,
+tracked-state, visual-ownership, benchmark-run-set, and scratch-output policy;
+it does not guess whether an arbitrary document is useful.
 and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
 enums when a generated or mechanically validated representation is available.
 
@@ -195,7 +214,7 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
 3. **Animated committed outputs**: Every active source uses `meta.animation: "trace"`. Each interactive HTML is the primary animated explorer, and each self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. Deterministic receipts are committed under `docs/assets/diagrams/`.
 4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
-5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
+5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The review at `docs/diagrams/reviews/` binds the current source and SVG hashes as a review assertion and is never generated or overwritten; the checker does not independently authenticate the reviewer. Run `npm run docs:diagrams:check` before review.
 6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
 
 ForgeLoop governs five documentation-diagram categories: workflow,
@@ -213,14 +232,16 @@ README hero assets are branding/conceptual architecture illustrations. They are
 not the canonical protocol diagram. The typed Archify workflow under
 `docs/diagrams/` remains the canonical lifecycle architecture source, with
 generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
-transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`.
+transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`. The current
+repository-only assets are `docs/assets/forgeloop-architecture.svg` and
+`docs/assets/forgeloop-lifecycle-animated.svg`; neither is a package file.
 
 The README hero is intentionally GitHub-repository-only:
 
-- `README.md` may reference `docs/assets/eng_readme_forgeloop.png`; GitHub
-  renders it from the repository.
-- The hero PNG is excluded from the npm package (`package.json` `files`), and
-  `tests/package.test.js` asserts that exclusion so it cannot be silently
+- `README.md` references `docs/assets/forgeloop-architecture.svg` for the hero
+  and `docs/assets/forgeloop-lifecycle-animated.svg` for the looping overview;
+  both are repository-only and excluded from the npm package.
+- `tests/package.test.js` asserts those exclusions so they cannot be silently
   re-included.
 - The packaged README is therefore not self-contained for that relative hero
   path; do not claim otherwise.

package/docs/JEV_BENCHMARKS.md

@@ -0,0 +1,31 @@
+# Jev benchmark and calibration
+
+`npm run benchmark:jev` emits an offline deterministic baseline for model-route
+scenarios. It records the pinned engine/model, safety-floor projection, fallback
+status, Jev/cache/latency fields, context and tool dimensions, and unknown host
+telemetry. Zero counts mean that no provider request was made; `null` and
+`NOT_MEASURED` remain explicit when the host did not observe a value. It does
+not fabricate provider usage and does not authorize lifecycle, execution,
+pruning, or completion.
+
+Provider-backed calibration requires a live TypeSafe organization with credits;
+an unavailable provider is reported as unavailable rather than treated as a
+successful benchmark.
+
+`npm run benchmark:jev:live` runs bounded intake, route, and context requests
+through the pinned Jev provider and reports provider usage/latency only when the
+provider supplies it. It requires `TYPESAFE_API_KEY`, never prints that key,
+and is intentionally separate from the offline benchmark.
+
+An optional maintainer release check is available through
+`npm run jev:smoke` and `npm run benchmark:jev:live`. The current repository does
+not enforce either live command in CI or the release workflow, and the CLI does
+not bind either command to an exact candidate commit. Offline output, a missing
+credential, or a provider-unavailable result is never a substitute for live
+interoperability evidence.
+
+Dependency audit attribution for the current base and PR head is unchanged:
+one high-severity `js-yaml` advisory (`GHSA-2883-xcg3-v3hh`, CVSS 7.5, CWE-400
+and CWE-407) arrives transitively through `eslint` → `@eslint/eslintrc` →
+`js-yaml` 4.3.1. It is not introduced by the Jev dependency; the audit reports
+an available upgrade outside this correction's runtime dependency policy.

package/docs/MODEL_ROUTING.md

@@ -0,0 +1,37 @@
+# Model routing
+
+ForgeLoop exposes model routing as a bounded semantic-decision projection. It
+has `SEMANTIC_DECISION` authority only within the declared decision contract;
+it has no lifecycle, completion, evidence, ownership, installation, command, or
+publication authority. The deterministic policy establishes the safety floor:
+
+- `NONE` when no generation is required;
+- `STANDARD` for ordinary executable generation;
+- `PRIMARY` for security, architecture, migration, ambiguity, and other
+  high-risk signals.
+
+The deterministic floor currently emits `NONE`, `STANDARD`, or `PRIMARY`. The
+public vocabulary also includes `FAST`, which is available only as an advisory
+escalation and cannot lower the deterministic floor.
+
+The pinned Jev model (`jev-1.13.0`) may recommend an escalation or request an
+escalation when confidence is low. It can never lower the deterministic floor,
+select a vendor-specific model, execute a command, change lifecycle state,
+authorize ownership, or weaken verification requirements. ForgeLoop remains the
+authority for all lifecycle, evidence, safety, and completion decisions.
+
+For route execution, the same boundary applies to guide relevance: Jev can
+reorder or remove a selected non-mandatory guide only with sufficient
+confidence. Mandatory safety protection is derived from the canonical
+deterministic route reasons the router already produced (auth surface and the
+trust-boundary risks untrusted-input, personal-data, secrets, external-service,
+publication), so a `security` guide selected by `external-service` risk cannot be
+removed. Mandatory safety guides are retained and low-confidence removal
+recommendations are retained rather than treated as authority. The resulting
+guide set and profile are persisted in the route artifact, so the semantic
+recommendation materially affects routing without becoming lifecycle authority.
+
+The live Jev provider is not an authority substitute. Semantic-required
+model-routing operations consume a fresh persisted `MODEL_ROUTE` decision and
+fail closed when it is unavailable or stale; offline inspection may still
+project deterministic policy without making a network request.