@msn-control/liftoff 0.7.0 → 0.9.0

package/docs/cli-reference.md

@@ -5,6 +5,7 @@ Run `liftoff help` or command-specific help for the authoritative syntax:
 ```bash
 liftoff init --help
 liftoff migrate --help
+liftoff upgrade --help
 liftoff update --help
 ```
 
@@ -14,7 +15,7 @@ duplicates, and extra positional arguments fail before generation.
 ## Lifecycle
 
 ```text
-plan -> init or migrate -> validate and doctor -> update -> dev and infra helpers
+install -> upgrade CLI -> plan -> init or migrate -> validate and doctor -> update project -> dev and infra helpers
 ```
 
 | Command | Behavior |
@@ -24,6 +25,8 @@ plan -> init or migrate -> validate and doctor -> update -> dev and infra helper
 | `liftoff migrate <source>` | Creates a new sibling scaffold and filtered source copy without changing the source |
 | `liftoff validate [project]` | Validates manifest identity, durable files, workload metadata, and framework markers |
 | `liftoff doctor [project]` | Runs read-only workload-derived project and workstation diagnostics |
+| `liftoff upgrade` | Replaces a verified global npm installation with the exact canonical stable release exposed by the configured registry |
+| `liftoff upgrade --check` | Checks installation origin and registry parity without installing; exits 2 when an installable update exists |
 | `liftoff update [project]` | Applies safe managed drift immediately, preserves unforced conflicts and orphans, and records the resulting manifest |
 | `liftoff update --check` | Reports drift without preflight or mutation; exits 0 when clean and 2 when drift exists |
 | `liftoff update --force` | Applies safe changes and overwrites only the exact guarded conflicts reported by update |
@@ -38,6 +41,11 @@ plan -> init or migrate -> validate and doctor -> update -> dev and infra helper
 The former `liftoff create` command is intentionally rejected with guidance to
 use `liftoff init`; there is no compatibility alias.
 
+Generation, validation, doctor, and update consume the packaged
+[supported-stack baseline](supported-stack.md). The current contract uses
+Node.js 24 LTS, Python 3.14, Go 1.27, OpenTofu 1.12, OpenSpec 1.11, and Spec Kit
+1.0 release lines; these commands never resolve mutable latest versions.
+
 ## Planning and initialization options
 
 Common noninteractive inputs include:
@@ -53,13 +61,65 @@ Common noninteractive inputs include:
 --spec openspec|spec-kit
 --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
 ```
 
 Power Apps rejects API, pattern, cloud, region, frontend, and API environment
 options rather than ignoring them.
 
 Consent options are documented in [safety and consent](safety-and-consent.md).
+Repository governance defaults to `single-maintainer-gitflow`. It generates a
+local policy handoff only; `none` omits it. See
+[repository governance](repository-governance.md).
+
+OpenSpec projects use all 12 OpenSpec 1.11 workflows with both skills and
+commands. `--copilot-cloud` opts into the GitHub-hosted coding-agent workflow and
+agent definition; omission and `--no-copilot-cloud` keep it disabled.
+
+OpenSpec stores workflow profile and delivery globally. If the observed profile
+does not match Liftoff's complete contract, interactive runs request separate
+consent. Noninteractive `init` and `migrate` require
+`--configure-openspec-profile` to authorize the displayed
+`openspec config set` commands. The flag has no effect during `plan`, which
+never inspects or changes machine configuration.
+
+## CLI upgrade modes
+
+```bash
+liftoff upgrade
+liftoff upgrade --check
+liftoff upgrade --json
+liftoff upgrade --check --json
+```
+
+`liftoff upgrade` is an imperative request to replace the supported global npm
+installation of `@msn-control/liftoff`; it does not prompt or accept `--yes`,
+`--force`, `--install-tools`, project paths, or project dependency flags.
+Automatic replacement is refused for local dependencies, `npx` execution-cache
+copies, linked checkouts, unknown package-manager stores, ambiguous roots, or
+unsafe paths.
+
+Canonical npm's stable `latest` metadata selects one exact target. The effective
+configured npm registry remains the delivery path and must expose that exact
+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.
+
+`--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
+confined binary, and exact `Liftoff <version>` output. A failed install or
+verification is not automatically rolled back; use the exact-version repair
+command printed by Liftoff.
+
+JSON results use schema version 1 and expose only `mode`, `status`,
+`currentVersion`, applicable `targetVersion`, applicable `registryKind`, and a
+stable `reasonCode`. Status is one of `current`, `update-available`, `upgraded`,
+`blocked`, or `failed`. Child progress goes to stderr so stdout remains one JSON
+object.
 
 ## Update modes
 
@@ -75,6 +135,9 @@ Plain `liftoff update` is imperative and prompt-free. It applies safe new,
 missing, untouched-upgrade, clean-move, and recorded-state changes in
 interactive terminals, redirected streams, and automation. Local or user-owned
 conflicts are skipped and reported. Orphans are reported without deletion.
+During legacy governance adoption, preserved unrecorded conflicts remain
+outside manifest ownership and set local state to `handoff-partial` until a
+later update can write or byte-identically adopt every required artifact.
 
 Use `--check` whenever no project bytes may change. Human check mode prints each
 drift state and recommends plain update for safe changes or a reviewed
@@ -92,6 +155,10 @@ stack, GenAI pattern, framework, selected-agent, or user-supplied Power Apps
 starter identity changes, and it cannot bypass project-boundary, symlink,
 structural-collision, or manifest guards.
 
+For a breaking supported-stack release, inspect `liftoff update --check` before
+plain update. Restore an unwanted applied migration through version control;
+running an older CLI is not a supported automatic downgrade.
+
 ### Migration from 0.6.x
 
 The `--apply` flag was removed in 0.7.0. These are historical 0.6.x commands,
@@ -113,6 +180,8 @@ Machine-readable maintenance contracts bypass decorative presentation:
 ```bash
 liftoff validate --json
 liftoff doctor --json
+liftoff upgrade --json
+liftoff upgrade --check --json
 liftoff update --json
 liftoff update --check --json
 ```
@@ -125,7 +194,8 @@ Exit codes:
 
 - `0`: success or a clean check.
 - `1`: invalid input, unsafe state, or command failure.
-- `2`: explicit update check mode found drift.
+- `2`: an explicit update check found project drift, or upgrade check found an
+  installable CLI release.
 
 Raw installer, framework, and dependency child stdout and stderr are forwarded
 unchanged.

package/docs/configuration-and-manifests.md

@@ -24,6 +24,7 @@ A Power Apps configuration contains only applicable fields:
   "projectType": "power-apps-code-app",
   "specWorkflow": "openspec",
   "agents": ["github-copilot"],
+  "governanceProfile": "single-maintainer-gitflow",
   "codeAppsPlugin": false
 }
 ```
@@ -33,7 +34,7 @@ workload rather than silently ignored.
 
 ## `liftoff.manifest.json`: CLI-owned compatibility record
 
-New projects use manifest schema v4. Its common project identity includes the
+New projects use manifest schema v5. Its common project identity includes the
 name, spec workflow, selected agents, and applicable Spec Kit default. A
 discriminated `project.workload` object contains only fields valid for one
 workload:
@@ -50,6 +51,8 @@ The manifest also records:
 - Durable artifact logical names.
 - OS-neutral path-part arrays.
 - `sha256:` content hashes.
+- Repository governance profile, policy version, 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.
@@ -60,16 +63,21 @@ paths, or hashes.
 
 ## Compatibility
 
-Readers support schemas v2, v3, and v4:
+Readers support schemas v2, v3, v4, and v5:
 
 - 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.
+- V5 adds repository-governance handoff identity without claiming live
+  enforcement.
 
 `liftoff update --check`, including `--check --json`, leaves an old manifest
-byte-for-byte unchanged. A successful plain update writes v4 only after the
-file transaction succeeds. Skipped conflicts retain their recorded hashes.
+byte-for-byte unchanged. A successful plain update writes v5 only after the
+file transaction succeeds. Previously recorded skipped conflicts retain their
+hashes. A preserved unrecorded governance conflict has no artifact entry and
+sets the update-written manifest to `handoff-partial`; resolving every such
+conflict promotes the next manifest to `handoff-generated`.
 
 ## Artifact ownership
 
@@ -88,7 +96,7 @@ can follow their own lifecycle.
 
 ## Contract conventions
 
-- Writers use `artifactVersion` 4; readers support v2, v3, and v4.
+- Writers use `artifactVersion` 5; readers support v2, v3, v4, and v5.
 - Artifact logical names and catalog identifiers are append-only.
 - Rendering is deterministic and does not depend on timestamps, host versions,
   or network state.

package/docs/existing-repositories.md

@@ -42,12 +42,13 @@ from unexpectedly treating that subdirectory as the repository root.
 Liftoff never blindly replaces a target tree. It:
 
 1. Renders Liftoff-owned files in temporary staging.
-2. Runs the official OpenSpec or Spec Kit initializer in staging.
-3. Rejects unexpected roots, nested Git metadata, and unsafe paths.
-4. Compares every destination before writing.
-5. Lists different regular files as one replacement set.
-6. Requires explicit overwrite permission before replacing that set.
-7. Applies the authorized merge transactionally and rolls back handled
+2. Verifies or separately configures the required global OpenSpec profile.
+3. Runs the official OpenSpec or Spec Kit initializer in staging.
+4. Rejects unexpected roots, nested Git metadata, and unsafe paths.
+5. Compares every destination before writing.
+6. Lists different regular files as one replacement set.
+7. Requires explicit overwrite permission before replacing that set.
+8. Applies the authorized merge transactionally and rolls back handled
    failures.
 
 Unrelated existing files are preserved. Structural collisions, symlinks,
@@ -74,6 +75,40 @@ automation, while preserving conflicts and orphans. Review every reported
 conflict and commit or copy local work before choosing `liftoff update --force`.
 For CI drift gates, use `liftoff update --check --json`.
 
+OpenSpec skills and commands remain framework-owned. To give an existing
+project all 12 workflows as both skills and commands, run:
+
+```bash
+openspec config profile
+openspec update
+```
+
+Select both delivery modes and every workflow in the profile picker. Plain
+`liftoff update` does not regenerate OpenSpec integrations. To change the
+hosted Copilot agent later, update `githubCopilot.cloudAgent` through OpenSpec
+and run `openspec update`.
+
+Projects created before manifest schema v5 automatically preview the default
+repository-governance handoff as new named drift. Plain update safely adopts
+collision-free policy, context, guide, and selected-agent launchers without
+rewriting a configuration that omitted `governanceProfile`. Existing different
+files remain unowned conflicts and the v5 manifest records `handoff-partial`.
+Resolving every conflict promotes a later update to `handoff-generated`.
+Selecting `none` leaves previously managed handoff files as undeleted orphans
+while unrecorded conflicts remain user-owned. No update mode runs an agent or
+activates GitHub settings.
+
+Major supported-stack releases can report many runtime, lock, Docker, provider,
+and framework artifact changes at once. Treat those releases as breaking:
+commit or copy local work, inspect `liftoff update --check`, and apply only after
+reviewing all upgrades and conflicts. Plain update preserves conflicting local
+bytes and never requires `--force` as the default migration path.
+
+If an applied baseline migration must be reversed, restore the project and
+manifest through version control and reinstall from the restored locks. Liftoff
+does not automatically downgrade generated dependencies and retains no backup
+after a successful update.
+
 ## Existing non-Liftoff application
 
 Use migration when you want a fresh governed scaffold and a filtered source
@@ -84,8 +119,9 @@ liftoff migrate ../legacy-app --region eastus --agents copilot,claude --yes
 ```
 
 Migration requires a new or empty sibling target, runs the same readiness and
-framework pipeline, and leaves the source byte-for-byte unchanged. `--force`
-does not permit a non-empty migration target.
+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.

package/docs/getting-started.md

@@ -5,8 +5,8 @@ standard APIs, and Power Apps code apps.
 
 ## 1. Install the CLI
 
-Liftoff requires Node.js 20.19 or newer. Power Apps code app projects require
-Node.js 22.12 or newer for their generated framework.
+Liftoff and generated Node.js workloads require Node.js 24.20 or newer.
+Python workloads use Python 3.14 with frozen `uv` dependency locks.
 
 The canonical release registry is `https://registry.npmjs.org`:
 
@@ -23,6 +23,18 @@ canonical npm. Stop if the mirror is older or rejects the explicit current
 version; ask the mirror owner to synchronize or approve the release. Liftoff
 does not modify `.npmrc` or bypass registry policy.
 
+Versions predating the self-upgrade command require that manual global install
+once. After a capable version is installed globally with npm, use:
+
+```bash
+liftoff upgrade --check
+liftoff upgrade
+```
+
+`upgrade` replaces only the supported global CLI installation. It does not read
+or update a generated project; inspect project template changes separately with
+`liftoff update --check`.
+
 See [prerequisites](prerequisites.md) for the complete plan-derived tool model.
 
 ## 2. Start interactive initialization
@@ -37,16 +49,25 @@ The guided flow asks for:
 
 1. Project identity and workload: GenAI, API, or Power Apps code app.
 2. Only the architecture choices applicable to that workload.
-3. OpenSpec or Spec Kit.
-4. One or both coding agents. On a real TTY, Space toggles agents and Enter
+3. Whether to generate the default single-maintainer GitFlow repository-
+   governance handoff. Accepting it creates local files only.
+4. OpenSpec or Spec Kit.
+5. One or both coding agents. On a real TTY, Space toggles agents and Enter
    confirms the selection.
-5. A Spec Kit default agent when both agents are selected.
-6. The optional Preview Code Apps plugin preference for Power Apps projects.
-7. Plan confirmation, workstation readiness, and any separate install or
+6. Whether to configure the default-off GitHub-hosted Copilot coding agent when
+   OpenSpec and GitHub Copilot are selected.
+7. A Spec Kit default agent when both agents are selected.
+8. The optional Preview Code Apps plugin preference for Power Apps projects.
+9. Plan confirmation, workstation readiness, and any separate install or
    overwrite permissions that are needed.
 
 Liftoff renders into temporary staging, runs the official framework initializer
 there, validates the complete result, and only then merges it into the target.
+OpenSpec projects use all 12 OpenSpec 1.11 workflows as both skills and commands.
+If the global OpenSpec profile differs, Liftoff displays the exact global change
+and asks separately before staging.
+Governance activation is a later selected-agent action after commit and push;
+see [repository governance](repository-governance.md).
 
 ## 3. Understand the target
 
@@ -94,8 +115,12 @@ liftoff plan --type power-apps-code-app --spec openspec --agents copilot
 
 Automation can pass the same options to `liftoff init`. Use `--yes` for project
 defaults and confirmation only. It does not authorize file replacement,
-machine-level tools, or project dependency installation. Those permissions
-remain independent.
+machine-level tools, global OpenSpec profile changes, Copilot cloud opt-in, or
+project dependency installation. Those permissions remain independent.
+
+Use `--configure-openspec-profile` only after reviewing the machine-wide change.
+Use `--copilot-cloud` to opt into the hosted agent or `--no-copilot-cloud` to
+record the safe default explicitly.
 
 See the [CLI reference](cli-reference.md) and
 [safety and consent](safety-and-consent.md) before automating initialization.

package/docs/prerequisites.md

@@ -6,13 +6,21 @@ and a Go API is not asked to install Python.
 
 ## Baseline
 
-- Liftoff CLI: Node.js 20.19 or newer.
-- Power Apps code app: Node.js 22.12 or newer.
-- Selected framework: the Liftoff-tested OpenSpec or Spec Kit contract.
+- Liftoff CLI and generated Node.js workloads: Node.js 24.20 or newer.
+- Python projects: Python 3.14 and `uv` 0.12.7 or newer.
+- Go projects: Go 1.27 or newer.
+- Generated Azure infrastructure: OpenTofu 1.12.6 or newer.
+- Selected framework: OpenSpec 1.11.0 or Spec Kit 1.0.1 exactly.
 - Selected agents: GitHub Copilot, Claude Code, or both.
 
+Automatic `liftoff upgrade` additionally requires that the running canonical
+`@msn-control/liftoff` package is a normal global npm installation beneath
+`npm root --global`. Local dependencies, `npx` cache copies, linked checkouts,
+and other package-manager stores use the documented manual global npm command
+instead. Liftoff never requests elevation.
+
 API workloads additionally require their selected Python, Node.js, or Go
-runtime. GenAI uses Python 3.12 and the Python/FastAPI/PydanticAI stack.
+runtime. GenAI uses Python 3.14 and the Python/FastAPI/PydanticAI stack.
 
 ## Blocking and advisory checks
 
@@ -21,6 +29,7 @@ Blocking checks must be ready before initialization can safely complete:
 - Required runtime and minimum version.
 - Selected spec framework CLI.
 - Every selected coding agent.
+- For OpenSpec, global profile `custom`, delivery `both`, and all 12 workflows.
 
 Advisory checks describe useful but deferrable capabilities:
 
@@ -32,6 +41,11 @@ Advisory checks describe useful but deferrable capabilities:
 Authentication checks are read-only. Liftoff never stores credentials or signs
 in to a cloud or agent on your behalf.
 
+The default repository-governance handoff has no additional initialization
+prerequisite. `gh`, a remote, licensed GitHub security features, private runners,
+Slack, and deployment access are discovered only during post-push Phase 0 and
+may be reported as gaps; they do not block local generation.
+
 ## Preview requirements without writes
 
 `liftoff plan` shows both generated artifacts and workstation requirements
@@ -56,6 +70,22 @@ An install that changes `PATH` is re-probed when possible and may require a new
 terminal. Do not treat installer success as readiness until the corresponding
 probe passes.
 
+## OpenSpec global profile consent
+
+OpenSpec 1.11 stores workflow selection and delivery globally rather than in a
+project. Liftoff requires all workflows with both skills and commands so a fresh
+project does not immediately drift when OpenSpec is rerun.
+
+Profile inspection is read-only. When the profile differs, interactive runs
+show the observed values, required values, and exact `openspec config set`
+commands before asking. Noninteractive runs stop unless
+`--configure-openspec-profile` is present. This authorization is independent of
+`--yes`, `--force`, and tool or dependency installation.
+
+The authorized change is verified before project staging. Because it is a
+machine-wide user preference, Liftoff reports it separately and does not restore
+an older profile if a later project phase fails.
+
 ## Project dependency consent
 
 Project-local dependency setup is separate from workstation tools and requires
@@ -76,6 +106,19 @@ the project is ready.
 GenAI and API projects use their generated stack-native locked dependency
 commands.
 
+Python projects use the generated lock without resolving new versions:
+
+```bash
+uv sync --frozen --project backend --extra test
+```
+
+Worker-enabled GenAI projects add `--extra functions`. Node.js projects use
+`npm ci`, and Go projects use `go mod download`.
+
+Liftoff's npm locks are generated with npm 12.0.2 and verified in the supported
+compatibility lanes. Do not replace a committed lock with an install from
+open-ended manifest ranges.
+
 ## Power Apps local CLI
 
 The Power Apps CLI is supplied by the generated project dependency graph.

package/docs/project-structure.md

@@ -14,7 +14,13 @@ project/
 |-- .env.example
 |-- Dockerfile
 |-- docker-compose.yml
+|-- .liftoff/
+|   `-- governance/             # durable local handoff when enabled
+|       |-- policy.md
+|       |-- context.json
+|       `-- README.md
 |-- backend/
+|   `-- uv.lock                 # Python stacks only
 |-- database/
 |   |-- alembic.ini or stack-native migration config
 |   |-- migrations/
@@ -26,7 +32,14 @@ project/
 |-- infrastructure/
 |   `-- opentofu/
 |       `-- azure/
+|           `-- .terraform.lock.hcl
 |-- openspec/ or .specify/
+|-- .github/skills/openspec-*/ and .github/prompts/opsx-*  # OpenSpec + Copilot
+|-- .claude/skills/openspec-*/ and .claude/commands/opsx/  # OpenSpec + Claude
+|-- .github/workflows/copilot-setup-steps.yml              # optional hosted agent
+|-- .github/agents/openspec.agent.md                       # optional hosted agent
+|-- .github/prompts/liftoff-repository-governance.prompt.md
+|   or .claude/commands/liftoff-repository-governance.md
 |-- frontend/                  # only when selected
 |-- functions/<worker-name>/  # only for worker-enabled GenAI patterns
 `-- migration/legacy/         # only after liftoff migrate
@@ -45,11 +58,18 @@ project/
   Functions settings when a worker is generated.
 - `docker-compose.yml` starts the selected backend, PostgreSQL, Redis,
   Azurite, and Mailpit. GenAI projects use pgvector where needed and include an
-  optional Langfuse profile.
+  optional Langfuse v4 web/worker profile backed by ClickHouse, dedicated Redis,
+  and MinIO.
+- Python Docker builds export the committed `uv.lock` in frozen mode and install
+  only hash-verified requirements. `UV_DEFAULT_INDEX` can select a
+  credential-free managed mirror without changing the lock.
 - `infrastructure/opentofu/azure` contains modules, environment tfvars, local
   state configuration, and a remote-state example.
 - `openspec` is created for OpenSpec. `.specify` and `specs` are created for
   Spec Kit.
+- OpenSpec projects receive all 12 pinned workflows as both skills and commands
+  for supported selected-agent surfaces. The two hosted Copilot agent files are
+  generated only after explicit opt-in.
 
 ### Conditional areas
 
@@ -87,6 +107,12 @@ project/
 `-- openspec/ or .specify/
 ```
 
+The exact selected-agent governance launcher is generated only when the
+repository-governance profile is enabled. It is Liftoff-owned; neighboring
+framework files remain framework-owned. Agent-created governance changes and
+`governance/activation-baseline.json` remain user-owned and are not listed in
+the manifest.
+
 This root follows the pinned official Microsoft starter. It includes the
 Power Apps SDK, Vite plugin, and project-local CLI through locked npm
 dependencies.

package/docs/repository-governance.md

@@ -0,0 +1,91 @@
+# Repository governance handoff
+
+Repository governance is a common Liftoff project choice. The default
+`single-maintainer-gitflow` profile generates a deterministic local handoff;
+`none` opts out:
+
+**Local handoff generated; live enforcement is not active.**
+
+```bash
+liftoff plan --governance single-maintainer-gitflow
+liftoff init --governance none
+```
+
+Accepting the default or passing `--yes` authorizes only local project files. It
+does not run an agent, mutate Git, contact GitHub, configure security, install a
+ruleset, deploy, or create monitoring.
+
+## Generated files
+
+An enabled profile adds durable, hash-managed artifacts:
+
+```text
+.liftoff/governance/policy.md
+.liftoff/governance/context.json
+.liftoff/governance/README.md
+.github/prompts/liftoff-repository-governance.prompt.md  # Copilot selected
+.claude/commands/liftoff-repository-governance.md        # Claude selected
+```
+
+The complete canonical policy is also packaged with Liftoff at
+[`assets/governance/single-maintainer-gitflow/policy.md`](../assets/governance/single-maintainer-gitflow/policy.md).
+It covers GitFlow, zero-human-approval repository rules, designated security
+tools, fail-closed checks, immutable release evidence, build-once promotion,
+deployment and rollback, monitoring and health, DORA metrics, ruleset
+sequencing, negative tests, documentation, and workload adaptation.
+
+`context.json` contains generated project facts only. GitHub repository state,
+runner access, licensed features, deployments, monitoring, alert routes,
+traffic, and rollout capabilities remain `undiscovered`. Power Apps context
+explicitly marks Liftoff backend, Docker, OpenTofu, custom container promotion,
+and API DAST as inapplicable.
+
+## Activate after commit and push
+
+1. Review the policy and context.
+2. Commit the project and push it to the intended GitHub repository.
+3. Run `/liftoff-repository-governance` with a selected agent.
+4. The agent performs read-only Phase 0 and reports repository identity,
+   artifacts, working commands, refs, workflows and exact checks, rulesets,
+   releases, environments, security, runners, deployments, monitoring, alerts,
+   health depth, platform capabilities, gaps, and inapplicable controls.
+5. The agent proposes the current `main` SHA as the activation baseline,
+   presents an ordered plan, and stops.
+6. Explicitly approve or revise the conversational plan. This is not a human
+   merge or deployment approval gate.
+7. After approval, the agent creates a new OpenSpec or Spec Kit governance
+   change, proves required contexts green and deliberately red, applies
+   repository-scoped rulesets last, and reads live enforcement back.
+
+The user-owned `governance/activation-baseline.json` is created only after
+approval. Liftoff never owns or recreates it or the agent-created governance
+change. Complete local handoffs say `handoff-generated`, partial adoptions say
+`handoff-partial`, and neither state means `active`.
+
+## Existing projects
+
+Configurations without `governanceProfile` normalize to the enabled default
+without rewriting `liftoff.config.json`:
+
+```bash
+liftoff update --check
+liftoff update
+```
+
+Check mode previews the schema-v5 manifest and new named artifacts without
+writing. Plain update applies collision-free files; differing existing files
+remain conflicts unless individually reviewed with `--force`. An unrecorded
+conflict remains outside Liftoff ownership and produces `handoff-partial`.
+After every conflict is removed or matches the current artifact, the next
+update records the full artifact set as `handoff-generated`.
+
+Setting `"governanceProfile": "none"` stops future rendering. Previously managed
+handoff files are reported once as orphans and left on disk; Liftoff never
+deletes them automatically or changes live repository settings.
+
+## Capability gaps
+
+Phase 0 must report missing GitHub licenses, private runners, staging access,
+monitoring routes, parallel-version mechanisms, or statistically meaningful
+canary traffic. It must mark controls inapplicable or blocked rather than
+creating a skipped, hanging, duplicate, or success-shaped placeholder.