@msn-control/liftoff 0.6.2 → 0.8.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,8 +25,11 @@ 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 update [project]` | Reports drift and, in an interactive terminal, explains impact and asks before applying |
-| `liftoff update --apply` | Applies safe changes, preserves unforced conflicts, and records the resulting manifest |
+| `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 |
 | `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 patterns` | Lists GenAI patterns |
@@ -37,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:
@@ -52,6 +61,7 @@ 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
 ```
 
@@ -59,35 +69,96 @@ 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).
+
+## 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
 
 ```bash
 liftoff update
+liftoff update --force
 liftoff update --json
-liftoff update --apply
-liftoff update --apply --force
+liftoff update --check
+liftoff update --check --json
 ```
 
-With interactive input and output, plain `liftoff update` first reports drift
-and its impact. Safe managed changes use a default-No confirmation. Local or
-user-owned conflicts are listed separately and require another default-No
-confirmation before replacement. Liftoff collects both decisions before any
-preflight or write.
+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.
 
-With redirected input or output, plain update remains a read-only check and
-prints the explicit apply command. `--json` also remains prompt-free and
-read-only unless combined with `--apply`. Explicit `--apply` and
-`--apply --force` bypass prompts for automation.
+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
+`--force` invocation for conflicts. `--check --force` is invalid because check
+mode never authorizes writes.
 
-The impact summary identifies affected dependency definitions, but update does
-not install dependencies. Orphans are reported without deletion. Transaction
-snapshots restore a failed update, but Liftoff retains no backup after a
-successful overwrite; commit or copy local work first.
+`--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
+update, but Liftoff retains no backup after a successful overwrite; commit or
+copy local work before using `--force`. Force does not permit workload, API
+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,
+not current syntax:
+
+| Historical 0.6.x command | 0.7.0 replacement |
+| --- | --- |
+| `liftoff update` when used as a read-only check | `liftoff update --check` |
+| `liftoff update --apply` | `liftoff update` |
+| `liftoff update --apply --force` | `liftoff update --force` |
 
-`--force` is valid only with `--apply`. It overwrites reported file conflicts;
-it does not permit workload, API stack, GenAI pattern, framework, selected
-agent, or user-supplied Power Apps starter identity changes.
+Invoking removed syntax fails during argument parsing, before project discovery
+or filesystem access.
 
 ## JSON and exit codes
 
@@ -96,16 +167,22 @@ 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
 ```
 
 Each JSON object has a top-level numeric `schemaVersion`.
+Operational warnings, such as a dirty-worktree warning before JSON apply, are
+written to stderr so stdout remains one parseable JSON object.
 
 Exit codes:
 
 - `0`: success or a clean check.
 - `1`: invalid input, unsafe state, or command failure.
-- `2`: a read-only check or declined interactive update 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,17 +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.
 
-A non-interactive or JSON check, or a declined interactive update, leaves an
-old manifest byte-for-byte unchanged. A successful explicit or interactively
-accepted apply writes v4 only after the file transaction succeeds. Skipped
-conflicts retain their recorded hashes.
+`liftoff update --check`, including `--check --json`, leaves an old manifest
+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
 
@@ -89,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

@@ -64,15 +64,36 @@ Use:
 
 ```bash
 liftoff validate
+liftoff update --check
 liftoff update
-liftoff update --apply
 ```
 
-In an interactive terminal, plain update reports drift and impact, then asks
-with a default of No before applying safe managed changes. Local or user-owned
-conflicts require a separate default-No overwrite decision. Redirected and
-JSON checks remain read-only and prompt-free; use `--apply` for explicit
-automation consent.
+Use `--check` first when the invocation must be read-only. Plain update applies
+safe managed changes immediately and without prompting in terminals and
+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`.
+
+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
 

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,20 @@ 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. A Spec Kit default agent when both agents are selected.
+7. The optional Preview Code Apps plugin preference for Power Apps projects.
+8. 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.
+Governance activation is a later selected-agent action after commit and push;
+see [repository governance](repository-governance.md).
 
 ## 3. Understand the target
 

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
 
@@ -32,6 +40,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
@@ -76,6 +89,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,10 @@ project/
 |-- infrastructure/
 |   `-- opentofu/
 |       `-- azure/
+|           `-- .terraform.lock.hcl
 |-- openspec/ or .specify/
+|-- .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,7 +54,11 @@ 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
@@ -87,6 +100,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.

package/docs/safety-and-consent.md

@@ -8,12 +8,35 @@ project dependencies. No one permission implies another.
 | Flag | Authorizes | Does not authorize |
 | --- | --- | --- |
 | `--yes` | Project defaults and plan confirmation | File replacement, machine installs, or project dependencies |
-| `--force` | Only listed and validated regular-file replacements | Manifest guards, symlinks, structural collisions, tools, dependencies, or non-empty migration targets |
+| `--force` | During init, listed regular-file replacements; during update, exact reported conflicts | Manifest guards, symlinks, structural collisions, tools, dependencies, or non-empty migration targets |
 | `--install-tools` | Allowlisted workstation installation commands | Project decisions, overwrites, or project dependencies |
 | `--install-dependencies` | Locked project-local dependency commands after a successful merge | Machine tools, project decisions, or overwrites |
 
 Interactive sessions ask separately at the point each permission is needed.
 
+Selecting repository governance or passing `--yes` authorizes only deterministic
+local handoff files. It never authorizes agent execution, Git mutation, GitHub
+APIs, rulesets, security configuration, deployment, monitoring, file
+replacement, machine tools, or project dependencies. Live activation begins
+only after commit, push, read-only Phase 0, and explicit plan approval.
+
+## CLI self-upgrade boundary
+
+`liftoff upgrade` is itself the narrow authorization to replace a supported
+global npm installation with one exact stable version. It accepts no project
+path, `--yes`, `--force`, tool-install, or dependency-install permission.
+`liftoff upgrade --check` is read-only and invokes no npm installation.
+
+Both modes operate from a temporary neutral directory so a project `.npmrc`
+cannot redirect machine-level discovery. Canonical npm selects the target while
+the configured registry must provide that exact release. Liftoff does not expose
+registry credentials, rewrite npm configuration, bypass a stale mirror, invoke
+`sudo` or another elevation mechanism, or touch project files.
+
+npm replacement is not a Liftoff file transaction. If npm or post-install
+verification fails, Liftoff reports an exact-version repair command and does not
+claim automatic rollback.
+
 ## Staged initialization
 
 Initialization does not write generated files directly into the destination.
@@ -50,11 +73,10 @@ Individual project files use temporary-file replacement. Initialization keeps
 backups for replaced files and records created files and directories. A handled
 merge failure restores or removes those entries in reverse order.
 
-An accepted interactive update or `liftoff update --apply` preflights all
-affected paths and applies generated file, move, delete, and manifest mutations
-as one rollback-capable transaction. Schema upgrades are committed only after
-the other mutations succeed. A corrected retry converges from the restored
-state.
+Plain `liftoff update` preflights all affected paths and applies generated file,
+move, delete, and manifest mutations as one rollback-capable transaction.
+Schema upgrades are committed only after the other mutations succeed. A
+corrected retry converges from the restored state.
 
 If automatic rollback itself cannot safely restore a path because another
 process changed it, Liftoff reports the incomplete rollback rather than
@@ -65,24 +87,27 @@ does not retain them as backups after success.
 
 ## Update ownership
 
-Plain `liftoff update` always reports drift before any write:
+Update mode is selected explicitly rather than from terminal interactivity:
 
 - Clean generated files remain unchanged.
-- In an interactive terminal, new, missing, untouched-upgrade, clean-move, and
-  recorded-state changes are summarized and offered through a default-No
-  confirmation.
-- With redirected input or output, or with `--json`, update remains a
-  prompt-free read-only check unless `--apply` is explicitly supplied.
+- Plain `liftoff update` immediately applies safe new, missing,
+  untouched-upgrade, clean-move, and recorded-state changes without prompting,
+  including with redirected input or output.
+- `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.
 - Developer edits that also differ from the current template are conflicts.
-- Safe-update consent does not authorize conflicts. Interactive conflicts are
-  listed by portable relative path and require a separate default-No overwrite
-  confirmation; automation uses `--apply --force`.
+- Default update skips conflicts and lists them by portable relative path.
+  After reviewing every listed overwrite, `liftoff update --force` extends the
+  transaction only to those guarded conflicts.
+- Unrecorded governance conflicts remain outside manifest ownership and produce
+  `handoff-partial` until a later update safely writes or adopts every artifact.
 - Orphans are reported and left on disk for manual review.
 - Dependency definitions may be updated, but update never installs
   dependencies.
 
-All interactive decisions are collected before preflight or mutation.
-Declining the safe update changes nothing and leaves drift exit code 2.
+`--force` cannot be combined with `--check` and cannot weaken project-boundary,
+symlink, collision, manifest, or transaction guards.
 
 Power Apps reconciliation reads only the packaged immutable starter. It does
 not fetch the upstream repository. Workload kind and user-edited starter