@msn-control/liftoff 0.11.1 → 0.11.2

package/docs/cli-reference.md

@@ -119,11 +119,21 @@ Governance JSON uses versioned objects and includes the complete activation
 version vector: creating Liftoff version, manifest artifact version 7, policy
 version 6, activation-contract version 2, state/evidence-header/approval schema
 versions 2, graph/supersession/credential schema versions 1, and the phase-graph
-hash. Compatibility metadata is version 2. It never
+hash. Compatibility metadata is version 3. It never
 emits a setup-skill version. Future identities, unsupported compatibility
 tuples, and unrecognized graph hashes block without rewriting state; the remedy
 names the exact field and required Liftoff upgrade. Known v1 history is
-diagnostic-only and byte-preserved; no automatic reconciliation command exists.
+diagnostic-only and byte-preserved; a supported successor requires
+`liftoff update --check` and explicit approval, not automatic reconciliation.
+
+Status, resume, and verify JSON include `migration` (the validated journal, or
+`null`) and `migrationSummary`. The summary separates `localCommit`, validated
+snapshot/index/successor linkage, recorded `revalidation`, `nextRecordedPhase`,
+and a project-bound fresh-preview remedy. `currentProofRequired` is always
+true: recorded completion is audit history, not current evidence or provider
+authority. Human output presents the same migration progress separately from
+readiness; stale current proof still blocks even when the journal says complete.
+These inspection commands neither advance phases nor create preview receipts.
 
 `/liftoff-setup` calls these commands instead of inferring phase completion from
 prose or task checkboxes.
@@ -256,16 +266,28 @@ object.
 ## Update modes
 
 ```bash
+liftoff update --check
 liftoff update
 liftoff update --force
-liftoff update --json
-liftoff update --check
 liftoff update --check --json
+liftoff update --approve-plan <fingerprint> --json
 ```
 
-Plain `liftoff update` is imperative and prompt-free. It applies safe new,
-missing, untouched-upgrade, clean-move, and recorded-state changes only for
-explicit `managed-core` artifacts. For manifest v7 this includes governance
+`liftoff update --check` is the human-first compatibility and migration preview.
+It changes no project bytes, but saves and discloses a project-bound preview
+receipt in user-local storage outside the repository. A receipt is not approval.
+`liftoff update` requires a matching preview, recomputes its effective plan, and
+asks for explicit approval with a negative default. Missing or stale previews
+stop with instructions to rerun check. No-op inspection requires no approval.
+
+Noninteractive apply additionally requires the exact full plan fingerprint
+through `--approve-plan`. Check and apply must share the same materialized
+checkout and user-local storage; another runner, worktree, or moved project
+needs a fresh check and approval. `--force`, `--json`, and a generic yes do not
+waive these gates. The force variant has its own preview and fingerprint.
+
+Approved apply retains safe new, missing, untouched-upgrade, clean-move, and
+recorded-state changes only for explicit `managed-core` artifacts. For manifest v7 this includes governance
 policy, context, guide, phase graph, compatibility metadata, credential-policy
 schema, and selected-agent `/liftoff-setup` integrations. Core conflicts are
 skipped and core orphans are reported without deletion. During legacy governance
@@ -288,22 +310,71 @@ recreates or deletes project files.
 New environments also require recorded independent-root infrastructure and safe
 existing shared-module files. Legacy/shared or unknown layout produces a
 component-level migration-required result; other safe managed-core work may
-continue. Force cannot migrate state or rewrite shared infrastructure.
+continue. Force cannot migrate infrastructure state or rewrite shared infrastructure.
+New component provisioning is deferred during activation-v1 migration and needs
+a fresh post-migration preview.
 
 Use `--check` whenever no project bytes may change. Human check mode prints
 managed-core drift, ownership-only manifest v2-v7 migration, activation-identity
-compatibility, reconciliation-required state, and authorized provisioning. It
-recommends `--force` only for core conflicts. `--check --force` is invalid
-because check mode never authorizes writes.
-
-`--json` selects output format, not safety. `liftoff update --json` applies safe
-changes and emits the versioned apply result. `liftoff update --check --json`
-is the read-only automation gate.
-
-Update never installs dependencies. Transaction snapshots restore a failed
-core update, but Liftoff retains no backup after a successful core overwrite.
-Force cannot bypass the ownership, project-boundary, symlink, structural,
-identity, or manifest guards.
+compatibility, history preservation, revalidation gaps, and authorized
+provisioning. It recommends `--force` only for eligible owned core conflicts
+and displays the additional exact changes and fingerprint separately.
+`--check --force` remains invalid because check mode never authorizes overwrites.
+
+`--json` selects output format, not safety or consent. Update JSON uses schema 3
+with project-update scope and separate core, provisioning, activation-migration,
+and revalidation outcomes. Prompts and progress use stderr; stdout remains one
+JSON result. Check exits 0 for no actionable work, 2 for differences, and 1 for
+errors. Apply exits 0 for completed scope, 2 when migration committed but
+revalidation is incomplete, and 1 for rejected approval or an error.
+
+Update never installs dependencies. Ordinary transaction backups are for failure
+recovery; activation migration additionally retains durable original history.
+Force cannot bypass preview, approval, ownership, project-boundary, symlink,
+structural, identity, or manifest guards.
+
+### Preview receipt storage
+
+Check reports the exact native receipt path. Receipts and separate transaction
+approval records use user-local storage, never the project or its containing
+repository:
+
+| Platform | Receipt directory |
+| --- | --- |
+| Linux | `$XDG_STATE_HOME/liftoff/update-previews` when `XDG_STATE_HOME` is set to an absolute path; otherwise, when unset, `$HOME/.local/state/liftoff/update-previews` |
+| macOS | `~/Library/Application Support/liftoff/update-previews` |
+| Windows | `%LOCALAPPDATA%\liftoff\update-previews` when `LOCALAPPDATA` is set to an absolute drive or UNC path; otherwise, when unset, `%USERPROFILE%\AppData\Local\liftoff\update-previews` |
+
+An empty or relative override is an error, not a request to use the fallback.
+Unsafe paths, links/junctions, or storage inside the project or repository also
+block the update; repair the reported storage issue rather than moving a receipt
+into the project. Commands containing spaces or shell metacharacters use literal
+native-shell quoting and retain the selected project path.
+
+The immutable history snapshot travels inside the project. Preview receipts and
+approval records do not: another machine, checkout, worktree, or moved project
+needs its own fresh check and approval. A receipt stores digests, not project
+source bodies, and is never portable blanket authorization.
+
+### Reviewed activation-v1 migration
+
+An exact supported v1 source can be previewed with `liftoff update --check`.
+Approved update verifies an immutable in-project history snapshot before
+replacing active records, then creates a linked strict v2 activation. Historical
+state, evidence, plans, approvals, and source metadata retain their original
+bytes under the dedicated governance history directory. History is not managed
+core and is never automatically committed, pushed, or cleaned with receipts.
+
+Fresh local revalidation does not translate old success flags or approvals.
+It uses only the finite reviewed local operations and stops before provider
+access, dependency installation, publication, or other independently approved
+work. Validation commands execute project-controlled code, not a sandbox;
+unexpected protected-input edits are preserved and reported.
+
+A failed local transaction uses bounded recovery. A failure after commit keeps
+v2 blocked and resumable: repair the named cause, rerun check, then approve the
+remaining work. Do not reset state to v1, change identity fields manually, or
+recreate live resources to silence readiness diagnostics.
 
 New dependency, runtime, container, database, application, and infrastructure
 templates apply to newly generated projects. Existing
@@ -330,10 +401,10 @@ All current writes use v7. Supported historical reads are normalized through an
 explicit compatibility map; future versions, individually known but unsupported
 tuples, and unknown phase-graph hashes block and report an upgrade or
 reconciliation remedy instead of downgrading or fabricating evidence.
-Exact known activation-v1 identity is readable for diagnostics. A
-`diagnosticOnly` historical-state result can coexist with managed-core maintenance,
-which preserves the historical identity, state, and receipts and does not make
-them executable.
+Exact known activation-v1 identity remains non-executable. The explicitly
+supported reviewed successor lane preserves that original history while
+establishing new v2 state and fresh proof; merely reading a historical identity
+or updating a core file does not perform or authorize the migration.
 
 ## Development and infrastructure helpers
 
@@ -370,8 +441,9 @@ liftoff update --check --json
 ```
 
 Each JSON object has a top-level numeric `schemaVersion`. Update JSON uses
-schema version 2 and includes `scope: "managed-core"`, ownership-migration
-state, activation compatibility, and a separate provisioning collection.
+schema version 3 and `scope: "project-update"`, with separate managed-core,
+provisioning, activation-migration, and revalidation outcomes plus preview and
+approval status. A committed migration does not imply governance readiness.
 Operational warnings, such as a dirty-worktree warning before JSON apply, are
 written to stderr so stdout remains one parseable JSON object.
 
@@ -379,8 +451,9 @@ Exit codes:
 
 - `0`: success or a clean check.
 - `1`: invalid input, unsafe state, or command failure.
-- `2`: an explicit update check found core maintenance or provisioning, or upgrade check found an
-  installable CLI release.
+- `2`: update check found differences, update committed a migration but local
+  revalidation is incomplete, or upgrade check found an installable CLI release.
+  Governance assessment also uses 2 for partial or excepted results.
 
 Raw installer, framework, and dependency child stdout and stderr are forwarded
 unchanged.

package/docs/configuration-and-manifests.md

@@ -197,7 +197,8 @@ policy, contract, schema, or graph identities remain invalid or blocked without
 rewrite.
 
 `liftoff update --check`, including `--check --json`, leaves an old manifest
-byte-for-byte unchanged. A successful plain update writes v7 only after the
+byte-for-byte unchanged while disclosing an external preview receipt. An
+explicitly approved update writes v7 only after the
 transaction succeeds. V2-v6 backend, frontend, database, dependency, container,
 environment, documentation, and infrastructure entries become
 project provenance without reading or changing current production bytes.
@@ -209,27 +210,38 @@ comparisons to infer execution safety.
 
 | Contract | Current version |
 | --- | --- |
-| CLI package version | 0.11.1 |
+| CLI package version | 0.11.2 |
 | Activation package identity | 0.11.0 |
 | Manifest write / supported reads | 7 / 2-7 for API and GenAI |
 | Normative policy | 6 |
-| Activation contract, state, evidence header, approval envelope, compatibility metadata | 2 |
+| Activation contract, state, evidence header, approval envelope | 2 |
+| Compatibility metadata / supported historical input | 3 / 2 |
+| Update report | 3 |
+| Preview receipt, transaction approval, history index, migration journal | 1 |
 | Phase graph, supersession, credential policy | 1 |
 | Assessment report and control catalog | 1 |
 
-The 0.11.1 CLI patch retains the 0.11.0 activation identity because its phase
+The 0.11.2 CLI patch retains the 0.11.0 activation identity because its phase
 semantics and graph are unchanged. Independent infrastructure provenance
-explicitly recognizes both generation versions; unknown releases are not
-automatically trusted or treated as compatible.
-
-Known activation-v1 history remains readable but **diagnostic-only**, not
-executable proof. Managed-core maintenance can continue without rewriting user-owned
-historical identity, state, or receipts. A readable historical manifest cannot
-bootstrap current activation or authorize provider scope, even when no state
-file exists or a separate current state is supplied. No automatic conversion, reset, or public
-historical reconciliation workflow is provided. Future/mixed tuples, ad hoc
-state, and unknown graph hashes remain blocked. No reader converts prose,
-filenames, checked tasks, or old placeholder digests into current evidence.
+explicitly recognizes generation versions 0.11.0, 0.11.1, and 0.11.2, including
+mixed component histories; unknown releases are not automatically trusted or
+treated as compatible. The mandatory preview/approval workflow and schema-3
+update reports are breaking CLI behavior despite the patch version.
+
+Known activation-v1 history remains **diagnostic-only**, not executable proof.
+Compatibility metadata v3 separately declares the exact history-preserving
+successor lane available through `liftoff update --check` and explicitly
+approved update. Schema-2 metadata remains readable input, not authority to
+invent a migration. Future/mixed tuples, ad hoc state, and unknown graphs remain
+blocked.
+
+Migration preserves the original manifest, historical state and evidence, creates
+strict v2 state, and links it through `governance/migration-state.json` to its
+immutable `governance/history` snapshot. No required field is added to manifest
+v7 or the v2 proof schemas. Original generation provenance remains intact.
+A readable historical record never authorizes current provider scope; old
+approvals and checked tasks do not become fresh evidence. Revalidation failure
+after local commit leaves the linked v2 activation blocked and resumable.
 
 ## Artifact ownership
 

package/docs/existing-repositories.md

@@ -70,11 +70,16 @@ liftoff update --check
 liftoff update
 ```
 
-Use `--check` first when the invocation must be read-only. Plain update applies
-safe managed-core changes immediately and preserves core conflicts and orphans.
-`--force` can replace only listed core conflicts. Project-owned production
-files are not compared and remain unreachable from every update mode. For CI
+Always run `--check` before a write-capable update. Check leaves project bytes
+unchanged and discloses a user-local preview receipt outside the repository.
+Plain update requires a matching preview and explicit approval of the exact
+plan before applying safe managed-core changes; core conflicts and orphans stay
+protected. `--force` requires separate approval of its previewed variant and
+can replace only listed, owned core conflicts. Project-owned production
+files are not compared with new templates or overwritten by update. For CI
 core-maintenance gates, use `liftoff update --check --json`.
+See [preview receipt storage](cli-reference.md#preview-receipt-storage) for
+platform-specific locations and checkout portability.
 
 OpenSpec skills and commands remain framework-owned. To give an existing
 project all 12 workflows as both skills and commands, run:
@@ -90,8 +95,9 @@ hosted Copilot agent later, update `githubCopilot.cloudAgent` through OpenSpec
 and run `openspec update`.
 
 Projects created before manifest artifact version 7 automatically preview the
-default deterministic setup handoff as new named drift. Plain update safely
-adopts collision-free policy, context, guide, phase graph, compatibility
+default deterministic setup handoff as new named drift. After a matching check
+and explicit approval, update safely adopts collision-free policy, context,
+guide, phase graph, compatibility
 metadata, credential-policy schema, and selected-agent setup integrations
 without rewriting a configuration that omitted `governanceProfile`.
 Existing different files remain unowned conflicts and the v7 manifest records
@@ -107,10 +113,13 @@ canonical phase graph, private-runner credential contract, bootstrap-state
 retention/disposal contract, and active-change reconciliation before
 replacement. Updating the handoff never provisions Azure or GitHub resources;
 active downstream work must have supported identity and current evidence before
-it can execute. The CLI provides no public identity-acknowledgment or historical
-reconciliation workflow.
-Historical activation-v1 state and receipts are diagnostic-only, not
-automatically migrated or made executable by updating core files.
+it can execute. Exact supported activation-v1 migration is previewed through
+`liftoff update --check` and requires approval of that plan. Original state,
+receipts, plans, approvals, and source metadata are retained in in-project
+history before a linked v2 successor is created. Historical records stay
+non-executable; updating a core file does not make them current proof.
+Post-commit revalidation failure leaves v2 blocked and resumable. Unsupported
+source formats and independent infrastructure migrations remain separate blockers.
 
 The manifest-v7 transition releases every legacy non-core artifact into project
 provenance without writing, restoring, moving, or deleting its path.

package/docs/repository-governance.md

@@ -342,14 +342,18 @@ seed blocks Phase 0. Exactly one compatible active governance change is resumed.
 Multiple overlapping changes require a schema-valid supersession or archive
 record before any phase advances.
 
-Managed updates install new policy, graph, schema, compatibility metadata, and
-setup and assessment integrations without touching user-owned state. Forced update can remove
+Reviewed managed updates install new policy, graph, schema, compatibility metadata,
+and setup/assessment integrations without acquiring general state ownership.
+Forced update can remove
 exact retired generated setup-alias entries from older manifests. When a policy,
 activation-contract, schema, or graph-hash change affects active work, status
 reports `reconciliation-required` and identifies affected descendants. Historical
-activation-v1 state and evidence stay byte-preserved and diagnostic-only under
-activation v2. This release has no automatic historical-state reconciliation,
-reset, or conversion workflow; do not acknowledge a new identity by editing JSON.
+activation-v1 state and evidence remain byte-preserved and non-executable.
+`liftoff update --check` can preview an exact supported successor migration;
+explicitly approved apply preserves original history and creates linked v2 state.
+Fresh local revalidation stops at unsupported or independently authorized work.
+Failure after commit leaves v2 blocked/resumable, not reset to v1. Never
+acknowledge an identity by editing JSON or treat old approvals as current consent.
 
 ## Private staging and bootstrap retention
 

package/docs/safety-and-consent.md

@@ -117,10 +117,15 @@ Existing destination modes are preserved where supported, including POSIX 0600
 files. Windows does not provide equivalent POSIX mode-bit guarantees; this is
 not a promise to preserve all Windows ACLs or filesystem metadata.
 
-Plain `liftoff update` preflights every eligible managed-core or authorized
-create-only provisioning path and applies those writes, managed-core moves or
-deletes, and the manifest as one rollback-capable transaction. Schema upgrades
-are committed only after the other mutations succeed.
+`liftoff update --check` presents compatibility and the exact proposed changes,
+then discloses its external preview receipt without changing project bytes.
+Apply requires that matching preview and explicit exact-plan approval. It
+rechecks protected inputs under the project lock before writing. Noninteractive
+approval uses `--approve-plan <fingerprint>`, not a generic yes.
+
+The approved transaction preflights exact managed-core and create-only
+provisioning paths separately from any explicitly authorized activation migration.
+Schema/successor changes commit consistently with their manifest and history link.
 
 Managed update may install manifest v7, policy v6, activation-contract v2,
 phase graph, compatibility metadata, credential-policy schema, setup
@@ -130,17 +135,21 @@ immutable evidence, credential policies, active OpenSpec changes, and bootstrap
 retention/disposal records. If the current activation identity is future,
 unsupported, or graph-incompatible, update and setup block with a remedy instead
 of downgrading or rewriting state.
-Exact known historical v1 identity is a separate diagnostic-only case:
-safe managed-core maintenance may continue while preserving the recorded
-historical identity, state, and receipts. That maintenance never makes history
-executable or supplies a missing reconciliation workflow.
+Exact known historical v1 can use the reviewed successor lane, not in-place
+retagging. Original records are copied byte-for-byte into immutable in-project
+history before their exact active paths are retired or replaced. A linked v2
+activation obtains fresh evidence; historical approvals never become current
+permission. Unavailable revalidation remains an explicit blocker.
 
 If automatic rollback itself cannot safely restore a path because another
 process changed it, Liftoff reports the incomplete rollback rather than
 overwriting unknown bytes.
 
-Update snapshots exist only for rollback after a failed transaction. Liftoff
-does not retain them as backups after success.
+Ordinary transaction backups are for failed-write recovery. Activation history
+is different: it remains after success and is never removed with disposable
+preview receipts. A durable recovery journal must match a separately persisted
+external transaction approval; a project-local claim alone cannot authorize
+recovery. Post-commit revalidation failure preserves v2 and its historical link.
 
 Dependency execution has a different recovery boundary: installer scripts can
 write arbitrary project files, and a concurrent developer edit cannot be
@@ -154,12 +163,12 @@ literal-path recipe. This does not claim the entire scaffold was unchanged.
 Update mode is selected explicitly rather than from terminal interactivity:
 
 - Existing project artifacts are never compared with current template bytes.
-- Plain `liftoff update` immediately applies safe new, missing,
-  untouched-upgrade, clean-move, and recorded-state changes only for exact
-  managed-core artifacts.
-- `liftoff update --check` is read-only and performs no preflight or mutation.
-- `liftoff update --json` applies safe changes and returns an apply result;
-  `liftoff update --check --json` is the read-only machine drift gate.
+- Plain `liftoff update` applies the matching explicitly approved plan, retaining
+  safe managed-core classification and the separate migration/provisioning lanes.
+- `liftoff update --check` changes no project bytes but saves and discloses a
+  preview receipt outside the repository.
+- `--json` changes output formatting only; machine apply still requires the
+  matching preview and exact plan-fingerprint approval.
 - Managed-core developer edits are conflicts. Project edits are outside update.
 - Default update skips core conflicts and lists them by portable relative path.
   `liftoff update --force` extends authority only to those guarded core
@@ -179,8 +188,8 @@ Update mode is selected explicitly rather than from terminal interactivity:
 - Dependency definitions and locks are project-owned; update neither changes
   nor installs them.
 
-`--force` cannot be combined with `--check` and cannot weaken project-boundary,
-symlink, collision, manifest, or transaction guards.
+`--force` cannot be combined with `--check` and cannot weaken preview, approval,
+compatibility, project-boundary, symlink, collision, manifest, or transaction guards.
 
 Power Apps support is retired. Its manifests are rejected without fetching
 starter source, changing application files, or treating force as conversion

package/docs/troubleshooting.md

@@ -148,11 +148,12 @@ hand-edited unsafe path.
 
 ## Update reports managed-core conflicts or orphans
 
-`liftoff update` applies safe managed-core changes immediately and skips core
-conflicts.
+Run `liftoff update --check` before apply. `liftoff update` requires the matching
+preview and explicit approval, then applies its safe scope and skips core
+conflicts. A missing or stale receipt requires a fresh check, not force.
 
-- Use `liftoff update --check` for a read-only human report or
-  `liftoff update --check --json` for an automation drift gate.
+- Use `liftoff update --check` for a project-read-only human report or add
+  `--json` for automation. Both disclose an external preview receipt.
 - Project-owned application files never enter the report or mutation set.
 - Managed-core conflicts remain untouched by default.
 - Use `liftoff update --force` only after reviewing every listed path and
@@ -162,7 +163,8 @@ conflicts.
 - Update neither changes nor installs project dependencies.
 
 Commit or copy local work before overwriting. Transaction rollback protects a
-failed update, but Liftoff keeps no backup after success.
+failed ordinary update. Activation migration additionally retains original
+history after success; failed revalidation retains blocked/resumable v2.
 
 For a new governance policy or launcher conflict, review that exact local file
 before considering `liftoff update --force`; do not delete it or activate remote
@@ -258,8 +260,8 @@ or allow TCP and UDP 53 to exact custom resolver addresses.
 | `phase-blocked` | Read the phase, proof, and authority blocker; unavailable production or enrollment capabilities remain blocked. |
 | `evidence-stale` | Obtain fresh proof through supported, authorized execution from current inputs; never edit receipts or reuse stale headers as current inputs. |
 | `credential-expiring` | Rotate before the recorded lead time using the same App or PAT policy. |
-| `reconciliation-required` | Review the precise identity/input diagnostic. Historical v1 has no public reconciliation workflow; preserve its bytes rather than acknowledging a new identity by editing JSON. |
-| `identity-incompatible` | Upgrade when the supported tuple requires a newer CLI. Unknown or historical tuples cannot be made executable with force or invented mappings. |
+| `reconciliation-required` | Review `liftoff update --check`. An exact supported v1 source can use the approved history-preserving successor lane; unknown formats remain blocked. Never edit JSON to acknowledge identity. |
+| `identity-incompatible` | Upgrade when the supported tuple requires a newer CLI. A historical receipt never becomes executable through force, retagging, or an invented mapping. |
 | `enforcement-incomplete` | Prove exact required contexts green and deliberately red, then approve final enforcement before ruleset mutation. |
 | `disposal-pending` | Review retention, exact imported paths, destructive scope, and proof. Execution requires valid authority; there is no public approval-entry shortcut. |
 

package/docs/workloads.md

@@ -138,7 +138,8 @@ It does not convert workloads, change API stacks or GenAI patterns,
 or modernize production project templates. Retired workloads have no update or
 automatic migration path.
 
-Plain update applies safe core changes immediately. Use `liftoff update
---check` for read-only inspection. `--force` applies only to listed
-managed-core conflicts; project-owned source, dependencies, schemas,
-containers, environments, documentation, and infrastructure remain untouched.
+Start with `liftoff update --check`, which changes no project bytes and discloses
+an external preview receipt. Plain update requires that matching preview and
+explicit approval. `--force` applies only to its separately reviewed core
+conflicts; project-owned source, dependencies, schemas, containers, environments,
+documentation, and infrastructure remain outside replacement authority.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Interactive CLI for governed GenAI applications and APIs.",
   "type": "module",
   "license": "GPL-3.0-only",