@msn-control/liftoff 0.10.4 → 0.11.2

package/docs/cli-reference.md

@@ -39,10 +39,11 @@ install -> upgrade CLI -> plan -> init or migrate -> /liftoff-setup -> validate,
 | `liftoff update --check` | Reports core maintenance and provisioning without mutation; exits 0 when clean and 2 when actionable |
 | `liftoff update --force` | Overwrites only exact guarded managed-core conflicts; project-owned files remain unreachable |
 | `liftoff dev` | Prints workload-appropriate local development commands; it does not execute them |
-| `liftoff infra` | Prints OpenTofu guidance for API workloads and reports infrastructure as not applicable for Power Apps |
+| `liftoff infra` | Prints OpenTofu guidance for supported API/GenAI workloads without executing it |
 | `liftoff patterns` | Lists GenAI patterns |
 | `liftoff providers` | Lists provider availability |
 | `liftoff regions` | Lists available regions |
+| `liftoff regions --region <slug-or-alias>` | Resolves one region and filters the output; ambiguous or unknown values fail with guidance |
 | `liftoff regions search <query>` | Searches region names and slugs |
 | `liftoff --version` | Prints exactly one version line |
 
@@ -59,7 +60,7 @@ Node.js 24 LTS, Python 3.14, Go 1.27, OpenTofu 1.12, OpenSpec 1.11, and Spec Kit
 Common noninteractive inputs include:
 
 ```text
---type genai|standard|power-apps-code-app
+--type genai|standard
 --pattern <genai-pattern>
 --api python|node|go
 --cloud azure
@@ -70,7 +71,6 @@ Common noninteractive inputs include:
 --agents copilot,claude
 --default-agent copilot|claude
 --governance single-maintainer-gitflow|none
---code-apps-plugin | --no-code-apps-plugin
 --copilot-cloud | --no-copilot-cloud
 --configure-openspec-profile
 ```
@@ -80,8 +80,9 @@ Interactive initialization presents **I'm not sure yet - Generic GenAI
 starter** first and accepts it as the default. `liftoff patterns` lists this
 stable `generic` identifier alongside the eight specialized patterns.
 
-Power Apps rejects API, pattern, cloud, region, frontend, and API environment
-options rather than ignoring them.
+Power Apps and Code Apps plugin inputs are retired and rejected, including
+false/negated plugin flags. Existing retired manifests are not reinterpreted as
+supported workloads or ordinary Git repositories.
 
 Consent options are documented in [safety and consent](safety-and-consent.md).
 Repository governance defaults to `single-maintainer-gitflow`. It generates a
@@ -116,11 +117,23 @@ failure with verified evidence.
 
 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 1, graph/state/evidence/approval/
-supersession/credential schema versions, and the phase-graph hash. It never
+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 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.
+names the exact field and required Liftoff upgrade. Known v1 history is
+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.
@@ -144,8 +157,11 @@ liftoff governance assess [project] --live [--json]
 liftoff governance assess --project "path with spaces" --json
 ```
 
-Use an optional positional project or `--project`, never both. Nested working
-directories resolve to the nearest Liftoff project. Help needs no project or
+Use an optional positional project or `--project`, never both. It can identify
+an ordinary Git repository without a manifest. Nested working directories resolve
+to the nearest applicable Git or Liftoff boundary; invalid or retired inner
+manifests cannot be bypassed. No initialization or slash-command installation is
+required. Help needs no project or
 credential discovery. Only `assess` accepts `--live`; assessment rejects
 `--execute` (including `--execute=false`), `--force`, installation, automatic
 upgrade, and output-file flags before project access.
@@ -228,6 +244,12 @@ version. Liftoff never edits `.npmrc`, embeds registry credentials, forces a
 canonical bypass around a stale mirror, invokes elevation, installs a
 prerelease, or performs a downgrade.
 
+Machine-level `@msn-control:registry` takes precedence over the default
+`registry`, even when the default is canonical. The lookup runs from a neutral
+directory so project `.npmrc` files cannot change upgrade delivery. Canonical
+verification isolates both registry settings without changing persistent
+configuration; actual delivery still honors the configured mirror.
+
 `--check` performs the same origin, target, and parity checks without invoking
 installation. Apply uses one shell-free exact npm command with lifecycle scripts,
 audit, and funding prompts disabled, then verifies installed metadata, the
@@ -244,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
@@ -262,7 +296,7 @@ set local state to `handoff-partial`. Forced update may remove exact retired
 generated setup-alias entries from older manifests after review.
 
 Application source, tests, dependencies and locks, database assets, Docker and
-Compose files, environment files, documentation, Power Apps starter files, and
+Compose files, environment files, documentation, and
 OpenTofu topology are `project` artifacts after generation. Update does not
 compare them with newer templates, restore deleted paths, or overwrite them
 under `--force`.
@@ -273,24 +307,77 @@ preflighted together. Absent files are created and byte-identical files are
 adopted as provenance; any differing destination blocks the group even with
 `--force`. Disabling or re-enabling a previously provisioned group never
 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 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.
-
-New dependency, runtime, container, database, application, Power Apps starter,
-and infrastructure templates apply to newly generated projects. Existing
+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
 production projects adopt them through a separately reviewed project change.
 The existing `liftoff migrate` command only adopts a non-Liftoff source into a
 fresh target; it is not an in-place template upgrade.
@@ -314,6 +401,26 @@ 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 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
+
+`liftoff dev` and `liftoff infra` print commands rather than execute them.
+Infrastructure helpers use recorded layout, not merely new-looking paths.
+For a selected prod environment in the independent layout,
+`liftoff infra init --env prod` targets
+`infrastructure/opentofu/azure/environments/prod`; plan/apply use
+`-var-file=prod.tfvars` in that same root. Operational init uses the configured
+backend, not `-backend=false`. Only the local baseline disables backend
+initialization, separately for every selected root. Recursive formatting remains
+at the Azure parent to include the shared module.
+
+The eight explicitly retired flat-root identities remain old provenance, not
+aliases for new roots. See the [exact inventory](azure-deployment.md#explicit-flat-root-identity-retirement)
+and [native runtime recipes](configuration-and-manifests.md#application-runtime-configuration).
 
 ## JSON and exit codes
 
@@ -334,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.
 
@@ -343,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

@@ -18,11 +18,9 @@ Supported edits are reconciled by `liftoff update`:
   manifests; replace it with `staging` before validation or update.
 - Removing or re-enabling a previously provisioned component never deletes,
   restores, or overwrites its project-owned files.
-- Power Apps can change the optional Code Apps plugin preference; only manifest
-  intent and applicable managed-core context change.
 
-Workload kind, API stack, GenAI pattern, spec workflow, selected agents, and a
-user-supplied Power Apps starter source change are not ordinary updates.
+Workload kind, API stack, GenAI pattern, spec workflow, and selected agents are
+not ordinary updates.
 
 An undecided GenAI project records an explicit generic identity rather than
 omitting the pattern:
@@ -46,21 +44,98 @@ omitting the pattern:
 Changing `generic` to a specialized pattern later is a reviewed project
 migration because application files are project-owned; it is not an update.
 
-A Power Apps configuration contains only applicable fields:
+The `power-apps-code-app` workload and `codeAppsPlugin` configuration field are
+retired. They are rejected rather than ignored or converted to another workload.
 
-```json
-{
-  "projectName": "sales-hub",
-  "projectType": "power-apps-code-app",
-  "specWorkflow": "openspec",
-  "agents": ["github-copilot"],
-  "governanceProfile": "single-maintainer-gitflow",
-  "codeAppsPlugin": false
-}
+## Application runtime configuration
+
+These settings are separate from Liftoff desired state. Each backend resolves
+**process environment > selected local configuration file > nonsecret defaults**
+once per process. Restart after changing configuration; do not shell-source a
+file to make it work.
+
+| Backend | Default native file | Selected-file override |
+| --- | --- | --- |
+| Python/FastAPI, including GenAI | Project-root `.env`, resolved from `backend/config/settings.py`, not the working directory | `LIFTOFF_ENV_FILE` names a dotenv file |
+| Node.js/Fastify | Project-root `.env`, resolved from source or compiled configuration location | `LIFTOFF_ENV_FILE` names a dotenv file |
+| Go/Huma | `../runtime.config.json` when launched from `backend/` | `LIFTOFF_ENV_FILE` names a JSON object of string values |
+
+Override paths are relative to the startup working directory unless absolute.
+An explicitly selected missing, unreadable, or malformed file fails even when
+process values could otherwise satisfy startup. An absent default file is allowed
+when process values provide the required settings. All stacks need
+`DATABASE_URL` and `REDIS_URL`; model credentials are not required for operational
+endpoints.
+
+Python and Node validate dotenv assignments, balanced quotes, UTF-8, and NUL
+input before accepting a file. Use `KEY=value`, optional `export`, comments,
+and single- or double-quoted values. Node uses the runtime dotenv parser and
+rejects escaped quote delimiters that it would otherwise truncate; use the other
+quote style, for example `APP_NAME="Bob's API"`. Go uses `encoding/json`, not a
+dotenv dependency: numbers such as `PORT` must be quoted strings, and null or
+other non-string values are rejected.
+
+### Native development
+
+From the project root in a POSIX shell, prepare the documented local settings:
+
+```bash
+cp .env.example .env
+docker compose up -d postgres redis azurite mailpit
 ```
 
-API, cloud, region, frontend, and environment fields are rejected for this
-workload rather than silently ignored.
+Then run **only the selected backend** after its locked dependency preparation:
+
+| Backend | Native command |
+| --- | --- |
+| Python | `uv sync --frozen --project backend --extra test`, then `uv run --project backend uvicorn backend.apis.main:app --host 127.0.0.1 --port 8000` |
+| Node.js | `(cd backend && npm ci && npm run build && npm start)` |
+| Go | Copy `runtime.config.example.json` to `runtime.config.json`, then `(cd backend && go mod download && go run ./cmd/api)` |
+
+Worker-enabled Python projects add `--extra functions` to frozen synchronization.
+For a Python launch from `backend/`, use
+`uv run uvicorn --app-dir .. backend.apis.main:app --port 8000`; it still reads
+root `.env` without exporting the file's values. PowerShell users can use
+`Copy-Item` and `Set-Location` rather than the POSIX parenthesized commands.
+An explicit selector from `backend/` is `$env:LIFTOFF_ENV_FILE = '..\.env'`
+for Python/Node, or `'..\runtime.config.json'` for Go.
+
+Migration tools use the same resolved settings: Python Alembic, Node Drizzle,
+and Go's `make migrate` wrapper around the existing pinned Goose tool. Running
+migrations is a separate database mutation, not part of the startup probes.
+
+### Compose and integration boundaries
+
+Compose reads root `.env` for interpolation. Select a different dotenv file with
+`docker compose --env-file environments/<env>/backend.env up --build`, using an
+actually selected environment. Process values take precedence. Compose deliberately
+keeps PostgreSQL, Redis, and blob addresses container-reachable while forwarding
+the applicable model, messaging, CORS, and tracing settings.
+
+`/health` and `/ready` are local process/configuration endpoints, not dependency
+connectivity or production-readiness proofs. They make no model/provider request.
+Backend containers listen on 8000; the frontend container serves static files on
+80, mapped to 5173 by Compose.
+
+For GenAI:
+
+- `PYDANTIC_AI_MODEL` supports the locked `openai:`, `openai-chat:`, and
+  `openai-responses:` providers with `OPENAI_API_KEY` and optional
+  `OPENAI_BASE_URL`. Other providers need reviewed dependency/configuration work.
+- Redis Streams publishes to `REDIS_STREAM_NAME` using `REDIS_URL`.
+- `SERVICE_BUS_AUTH_MODE=managed-identity` requires
+  `SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE`, `SERVICE_BUS_QUEUE_NAME`, and
+  `AZURE_CLIENT_ID`. `connection-string` requires the queue and
+  `SERVICE_BUS_CONNECTION_STRING`. Missing sender settings cannot report queued
+  ingestion.
+- Both Langfuse keys blank means tracing is disabled; configuring exactly one
+  of `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` is an error.
+  `LANGFUSE_HOST` is optional.
+
+Keep local secrets out of source control and build contexts. Root/frontend
+`.dockerignore` files exclude host dependencies, caches, outputs, VCS metadata,
+state, and secrets; the Function publish context also has `.funcignore`.
+These runtime files remain project-owned, not managed update targets.
 
 ## `liftoff.manifest.json`: CLI-owned compatibility record
 
@@ -71,8 +146,6 @@ workload:
 
 - `genai`: API stack, pattern, cloud, region, frontend, and environments.
 - `standard`: API stack, cloud, region, frontend, and environments.
-- `power-apps-code-app`: immutable starter repository, template path, commit,
-  and Code Apps plugin preference.
 
 The manifest also records:
 
@@ -85,12 +158,14 @@ The manifest also records:
   authorize update writes.
 - OS-neutral path-part arrays.
 - Repository governance profile, policy version 6, activation-contract version
-  1, graph/state/evidence/approval/supersession/credential schema versions, the
+  2, state/evidence-header/approval schema versions 2,
+  graph/supersession/credential schema versions 1, the
   exact phase-graph hash, and local `handoff-generated`, `handoff-partial`, or
   disabled state.
 
-Power Apps source identity uses explicit repository, path, and 40-character
-commit fields. It is not inferred from mutable URLs or generated file paths.
+An existing Power Apps manifest is rejected at its retired workload boundary
+before starter metadata or artifact paths are interpreted. Its original files
+remain unchanged.
 
 Treat the manifest as CLI-owned. Restore it from version control or regenerate
 with the matching Liftoff version when validation reports malformed identity,
@@ -98,19 +173,20 @@ paths, or hashes.
 
 ## Compatibility
 
-Readers support artifact versions v2, v3, v4, v5, v6, and v7:
+Readers support artifact versions v2, v3, v4, v5, v6, and v7 for API/GenAI projects:
 
 - V2 normalizes the legacy flat API identity and records framework state as
   uncertain without inventing agents.
 - V3 normalizes flat GenAI or API identity plus framework and agent metadata.
-- V4 represents the discriminated workload model, including Power Apps.
+- V4 introduces the discriminated workload model. Its formerly supported Power
+  Apps variant is now retired.
 - V5 adds repository-governance handoff identity without claiming live
   enforcement.
 - V6 separates managed-core update authority from project generation
   provenance.
-- V7 adds deterministic setup identity: manifest artifact version 7, policy
-  version 6, activation-contract version 1, schema-v1 activation artifacts, and
-  the canonical phase-graph hash. Governance-disabled v7 manifests use the
+- V7 adds deterministic setup identity. Current output uses
+  manifest artifact version 7, policy version 6, activation-contract version 2, and the canonical
+  phase-graph hash. Governance-disabled v7 manifests use the
   disabled variant and do not fabricate activation identity.
 
 Enabled governance manifests retain their recorded positive-integer policy
@@ -121,20 +197,51 @@ 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, Power Apps, and infrastructure entries become
+environment, documentation, and infrastructure entries become
 project provenance without reading or changing current production bytes.
 Intentionally deleted files remain absent. Only exact current core logical names
 retain write authority.
 
 The compatibility map is explicit; Liftoff does not use numeric less-than
-comparisons to infer safety. Supported v7 identity resumes when policy 6,
-activation contract 1, schema versions 1, and a recognized graph hash match.
-Future identities, individually known versions in unsupported combinations,
-unversioned ad hoc governance state, and unknown graph hashes block with an
-upgrade, import-mapping, or reconciliation remedy. No reader converts prose,
-filenames, or checked tasks into evidence.
+comparisons to infer execution safety.
+
+| Contract | Current version |
+| --- | --- |
+| 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 | 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.2 CLI patch retains the 0.11.0 activation identity because its phase
+semantics and graph are unchanged. Independent infrastructure provenance
+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
 
@@ -149,6 +256,11 @@ category or filename:
 | `framework` | Official framework | Validated through framework markers and maintained by that framework |
 | `seed` | Developer/project | Written once and never reconciled |
 
+New Spec Kit projects explicitly seed
+`specs/000-liftoff-bootstrap/{spec.md,plan.md,tasks.md}`. These are not framework
+templates or managed-core files. Missing older bundles are an adoption blocker,
+not permission for update or force to create them.
+
 The manifest is a CLI-owned transaction record rather than an ordinary
 template artifact. Current managed core is limited to the exact repository
 governance policy, context, guide, phase graph, compatibility metadata,
@@ -174,7 +286,12 @@ those files, but it does not advance, reset, or delete a phase.
 ## Contract conventions
 
 - Writers use `artifactVersion` 7; readers support v2, v3, v4, v5, v6, and v7.
-- Artifact logical names and catalog identifiers are append-only.
+- Artifact logical names and catalog identifiers are append-only except for
+  explicitly reviewed retirements. In 0.11.0, the eight
+  [flat-root OpenTofu identities](azure-deployment.md#explicit-flat-root-identity-retirement)
+  are retired from **new scaffold output only**. Their historical paths,
+  identities, and generation hashes remain provenance, not aliases or deletion
+  authority. Retained tfvars IDs alone do not establish the independent layout.
 - Rendering is deterministic and does not depend on timestamps, host versions,
   or network state.
 - `.liftoff/governance/` contains managed setup definitions; `governance/`

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
@@ -102,12 +108,18 @@ while unrecorded conflicts remain user-owned. No update mode runs an agent or
 activates GitHub settings.
 
 Projects carrying governance policy versions 2 through 5 preview policy version
-6, manifest v7, and activation-contract v1 as managed-core drift. Review the
+6, manifest v7, and activation-contract v2 as managed-core drift. Review the
 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;
-any active downstream governance change must acknowledge the supported
-activation identity and exact graph hash before applying infrastructure.
+active downstream work must have supported identity and current evidence before
+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.
@@ -118,7 +130,16 @@ Supported readers normalize manifest v2-v6 and write only v7 after all
 preflights pass. Future versions, unsupported policy/contract/schema tuples,
 unknown graph hashes, unversioned activation state, or prose-only task history
 block with explicit upgrade, import-mapping, or reconciliation remedies. Liftoff
-never fabricates evidence from old checkboxes.
+never fabricates evidence from old checkboxes. A diagnostic is not a command to
+hand-write mappings, retag receipts, or manufacture missing history.
+
+The new infrastructure layout uses shared application modules and independent
+environment roots. Its eight [retired flat-root identities](azure-deployment.md#explicit-flat-root-identity-retirement)
+remain readable as historical provenance, not aliases for new paths. Existing
+files, state, and generation hashes remain untouched. Adding an environment
+requires recorded independent-root provenance and safe existing module files;
+legacy or unknown layouts need separately reviewed migration. Core context
+updates cannot claim that this migration happened.
 
 Major supported-stack releases apply to new scaffolds. Existing projects adopt
 runtime, lock, Docker, provider, framework, and application changes through a
@@ -146,5 +167,20 @@ framework pipeline, including separate global OpenSpec profile authorization,
 and leaves the source byte-for-byte unchanged. `--force` does not permit a
 non-empty migration target.
 
-Arbitrary existing Power Apps application migration is not currently
-supported.
+The scan reads dependency declarations rather than comments or example text.
+Python setup/test configuration and non-workflow `.github` files remain
+explicit inventory items; dynamic or malformed declarations produce review
+diagnostics rather than invented stack defaults. Source configuration code is
+never executed to discover dependencies.
+
+Explicit workload, API-stack, and frontend choices control the target mapping.
+For example, Go source selected for a Node target receives porting instructions,
+not Go-only destination paths; a declined frontend remains a placement decision.
+
+Complete the mapped work and run the backend tests, `liftoff validate`, and
+`liftoff doctor` before deleting `migration/legacy/`. OpenSpec archival follows
+the completed change; a Spec Kit migration checklist is finalized locally
+without an invented archive command.
+
+Power Apps creation, maintenance, and migration are retired. Existing Power Apps
+manifests are rejected without modifying or converting their application files.