@msn-control/liftoff 0.7.0 → 0.9.0

package/docs/safety-and-consent.md

@@ -1,33 +1,61 @@
 # Safety and consent
 
-Liftoff separates project decisions, file replacement, workstation tools, and
-project dependencies. No one permission implies another.
+Liftoff separates project decisions, file replacement, workstation tools,
+global OpenSpec profile configuration, Copilot cloud setup, and project
+dependencies. No one permission implies another.
 
 ## Consent flags
 
 | Flag | Authorizes | Does not authorize |
 | --- | --- | --- |
-| `--yes` | Project defaults and plan confirmation | File replacement, machine installs, or project dependencies |
-| `--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 |
+| `--yes` | Project defaults and plan confirmation | File replacement, machine installs, global OpenSpec changes, Copilot cloud opt-in, or project dependencies |
+| `--force` | During init, listed regular-file replacements; during update, exact reported conflicts | Manifest guards, symlinks, structural collisions, tools, global profile changes, dependencies, or non-empty migration targets |
+| `--install-tools` | Allowlisted workstation installation commands | Project decisions, overwrites, global profile changes, or project dependencies |
+| `--configure-openspec-profile` | The displayed global OpenSpec workflow, delivery, and profile changes | Tools, project files, dependencies, or Copilot cloud opt-in |
+| `--copilot-cloud` / `--no-copilot-cloud` | Enable or disable OpenSpec's project-local hosted Copilot agent files | Global profile changes, tools, dependencies, or unrelated project writes |
+| `--install-dependencies` | Locked project-local dependency commands after a successful merge | Machine tools, global profile changes, 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.
 Liftoff:
 
 1. Resolves and validates a project plan.
-2. Renders Liftoff-owned artifacts into a temporary staging directory.
-3. Runs the official OpenSpec or Spec Kit initializer in staging.
-4. Rejects nested Git metadata, unexpected framework roots, symlinks, and
+2. Verifies the OpenSpec global profile when OpenSpec is selected and separately
+   authorizes any required machine-wide change.
+3. Renders Liftoff-owned artifacts into a temporary staging directory.
+4. Runs the official OpenSpec or Spec Kit initializer in staging.
+5. Rejects nested Git metadata, unexpected framework roots, symlinks, and
    malformed output.
-5. Validates the full staged project.
-6. Computes one immutable destination preflight.
-7. Shows every different regular file that would be replaced.
-8. Applies only an authorized preflight.
+6. Validates the full staged project.
+7. Computes one immutable destination preflight.
+8. Shows every different regular file that would be replaced.
+9. Applies only an authorized preflight.
 
 Unrelated destination files are preserved.
 
@@ -77,6 +105,8 @@ Update mode is selected explicitly rather than from terminal interactivity:
 - 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.
@@ -98,6 +128,13 @@ does not claim framework-owned files in durable artifact hashes.
 One-time seed content is also omitted from durable hashes so it can follow its
 own lifecycle after generation.
 
+OpenSpec workflow profile and delivery are global machine preferences. Liftoff
+changes them only after dedicated consent and verifies the result before
+staging. That global choice is not part of the project-file transaction and is
+not automatically rolled back after a later failure. The Copilot cloud choice
+is separate, defaults off, and is persisted by OpenSpec in the generated
+project config.
+
 ## Telemetry boundary
 
 Liftoff sends only a recognized command name, CLI version, and zero/nonzero

package/docs/spec-workflows-and-agents.md

@@ -7,19 +7,31 @@ Liftoff workload.
 
 ### OpenSpec
 
-OpenSpec organizes proposed behavior changes as reviewable artifacts before
-implementation. Liftoff runs the pinned official OpenSpec initializer in
-temporary staging and passes every selected coding agent in stable order.
+OpenSpec 1.11.0 organizes proposed behavior changes as reviewable artifacts
+before implementation. Liftoff runs that pinned official initializer in
+temporary staging, passes every selected coding agent in stable order, and
+requires the complete custom profile with both skills and commands:
 
-Generated projects contain `openspec/` plus the selected agent integration
-markers.
+```text
+propose, explore, new, continue, apply, update,
+ff, sync, archive, bulk-archive, verify, onboard
+```
+
+OpenSpec stores profile and delivery preferences globally. Before creating an
+OpenSpec project, Liftoff reads that configuration through the pinned CLI. A
+matching custom/both profile proceeds without a prompt. A different profile is
+blocking until you separately approve the displayed global changes or pass
+`--configure-openspec-profile`. `--yes` and other consent flags do not authorize
+the machine-wide change.
+
+Generated projects contain `openspec/` plus all 12 official workflow skills and
+commands for each selected agent surface that supports them.
 
 ### Spec Kit
 
-Spec Kit provides a specification, planning, and implementation workflow.
-Liftoff initializes the selected default coding agent first, adds every
-secondary integration, and records the default separately from the full agent
-set.
+Spec Kit 1.0.1 provides a specification, planning, and implementation workflow.
+Liftoff initializes the selected default coding agent first, adds every secondary
+integration, and records the default separately from the full agent set.
 
 Generated projects contain `.specify/`, `specs/`, and the selected agent
 integration markers.
@@ -66,6 +78,46 @@ Framework files remain owned by the official initializer. Liftoff validates
 them but excludes framework-owned output from durable artifact hashes so a
 framework can manage its own lifecycle.
 
+To align an existing OpenSpec project, configure both delivery and all workflows:
+
+```bash
+openspec config profile
+openspec update
+```
+
+Select **Both (skills + commands)** and every workflow in the profile picker.
+Plain `liftoff update` intentionally does not regenerate these framework-owned
+files.
+
+Repository-governance launchers are separate durable Liftoff files at the exact
+Copilot prompt and Claude command paths documented in
+[repository governance](repository-governance.md). They reference one canonical
+policy and context rather than duplicating framework-owned content. After
+read-only Phase 0 and explicit approval, the agent creates a new change using
+the selected framework; Liftoff never pre-creates or restores that change.
+
+Install the exact selected framework release with its supported package manager:
+
+```bash
+npm install -g @fission-ai/openspec@1.11.0
+uv tool install specify-cli==1.0.1
+```
+
+## Optional GitHub Copilot cloud coding agent
+
+When OpenSpec and GitHub Copilot are selected, Liftoff asks whether to configure
+GitHub's hosted coding agent. This is separate from Copilot in an editor or
+terminal and defaults to No.
+
+Opting in writes official OpenSpec-owned files:
+
+- `.github/workflows/copilot-setup-steps.yml`
+- `.github/agents/openspec.agent.md`
+
+Use `--copilot-cloud` or `--no-copilot-cloud` in automation. The choice is
+recorded as `githubCopilot.cloudAgent` in `openspec/config.yaml`; it is not stored
+as Liftoff overwrite or machine-configuration consent.
+
 ## Optional Code Apps plugin
 
 Power Apps projects can request Microsoft's

package/docs/supported-stack.md

@@ -0,0 +1,89 @@
+# Supported stack baseline
+
+Each Liftoff release packages one tested dependency baseline in
+`assets/supported-stack.json`. Project generation and update use that committed
+file; they never resolve mutable `latest` versions.
+
+## Runtime and framework baseline
+
+| Surface | Tested release |
+| --- | --- |
+| Node.js | 24.20.0 LTS |
+| npm | 12.0.2 |
+| Python | 3.14.7 |
+| `uv` | 0.12.7 |
+| Go | 1.27.0 |
+| OpenTofu | 1.12.6 |
+| OpenSpec | 1.11.0 |
+| Spec Kit | 1.0.1 |
+| AzureRM provider | 5.3.0 |
+| Power Apps SDK | 1.2.7 |
+
+Power Apps SDK 1.2.7 is an explicit compatibility selection. Versions 1.2.12
+and newer remove the project-local `power-apps` CLI required by Liftoff's
+current workload contract. Moving to Microsoft's global `pa` CLI is a separate
+reviewed workload migration; the freshness check recognizes only the recorded
+1.3.0 exclusion and will reopen the decision when a newer candidate appears.
+
+Generated npm projects include `package-lock.json`. Python projects include
+`uv.lock` and use `uv sync --frozen`. Go projects include `go.mod` and
+`go.sum`. Generated OpenTofu includes a multi-platform `.terraform.lock.hcl`.
+
+Container references include a readable stable tag and an immutable
+multi-architecture digest. The optional Langfuse profile uses the v4 web and
+worker services with pinned ClickHouse, Redis, and MinIO dependencies.
+
+## Refresh policy
+
+Maintainers compare the committed baseline with canonical ecosystem sources:
+
+```bash
+npm run check:supported-stack
+npm run check:supported-stack-freshness
+```
+
+The first command verifies that package manifests and lockfiles match the
+committed baseline. The second is a networked, fail-closed freshness check.
+A newer release is not promoted automatically: update manifests and source for
+compatibility, regenerate ecosystem-native locks, review immutable image
+digests and upstream provenance, then run:
+
+```bash
+npm run refresh:supported-stack
+npm run check
+npm run verify:standard-node-templates
+npm run verify:power-apps-starter
+```
+
+Power Apps source is refreshed only through its reviewed immutable upstream
+commit workflow. Do not edit Microsoft-owned starter files independently.
+
+## Existing generated projects
+
+Upgrade the globally installed Liftoff CLI, then inspect project-managed changes
+as a separate operation:
+
+```bash
+liftoff upgrade --check
+liftoff upgrade
+liftoff update --check
+liftoff update
+liftoff validate
+liftoff doctor
+```
+
+Untouched managed files and new lockfiles can be updated automatically.
+Locally modified files remain conflicts unless explicitly reviewed with
+`liftoff update --force`. Liftoff never installs the updated project
+dependencies during `update`; run the generated `npm ci`, `uv sync --frozen`,
+or `go mod download` command afterward. CLI upgrade does not discover or modify
+the project.
+
+This baseline is a breaking release boundary: it raises the Node.js, Python, Go,
+and OpenTofu floors and includes major framework, provider, frontend, container,
+and dependency migrations. Commit or otherwise preserve local work, run
+`liftoff update --check`, and review every named upgrade and conflict before
+applying. Do not use an older Liftoff release as an automatic downgrade tool.
+After a successful update, recover unwanted changes through version control and
+then reinstall from the restored locks; Liftoff does not retain a post-success
+backup.

package/docs/telemetry.md

@@ -24,6 +24,12 @@ code. It is an exit-status class, not an error diagnosis. Help requests are
 recorded as `help`, and rejected input that never resolves to a recognized
 command is not recorded.
 
+`upgrade` is recorded only as the aggregate command value. Check/apply mode,
+target or configured-registry details, installation origin, paths, npm output,
+reason codes, and errors are not added. The replacement binary's verification
+process runs with telemetry and disclosure disabled, so at most the originally
+invoked parent command emits an event.
+
 Liftoff does **not** send:
 
 - An installation, user, device, or session identifier.

package/docs/troubleshooting.md

@@ -7,6 +7,8 @@ Check the canonical release:
 ```bash
 npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org
 liftoff --version
+liftoff upgrade --check
+liftoff upgrade
 ```
 
 Versions before 0.3.0 are unsupported.
@@ -16,6 +18,40 @@ mirror owner to synchronize or approve the release. Liftoff does not modify
 `.npmrc`. A successful installation of an older mirrored package does not make
 that version supported.
 
+Versions that predate `liftoff upgrade` require one manual global installation:
+
+```bash
+npm install -g @msn-control/liftoff@latest --registry=https://registry.npmjs.org
+```
+
+## CLI upgrade is blocked by installation origin
+
+Automatic replacement supports only the canonical package at npm's effective
+global package root. A local dependency, `npx` cache copy, linked checkout, or
+another package-manager installation is intentionally refused. Use the manual
+global npm command shown by Liftoff; do not try to make upgrade replace a
+different installation.
+
+## CLI upgrade is blocked by a stale managed registry
+
+Canonical npm defines the exact stable target, but Liftoff installs through the
+configured registry. Ask the mirror owner to synchronize or approve that exact
+version, then rerun `liftoff upgrade --check`. Liftoff does not edit `.npmrc` or
+bypass the managed registry.
+
+## npm cannot write the global prefix
+
+Liftoff does not run `sudo`, request administrator credentials, or retry with
+elevation. Resolve Node/npm global-prefix ownership through the approved
+workstation process, then rerun the command.
+
+## CLI replacement verification fails
+
+Liftoff reports `failed` even when npm exited zero unless installed metadata and
+`liftoff --version` both match the exact target. Run the exact-version global npm
+repair command printed in the result. Liftoff does not claim an automatic
+rollback after npm may have partially changed global state.
+
 ## An installed tool is still reported missing
 
 Installers that change `PATH` may require a new terminal. Open one, rerun:
@@ -49,6 +85,43 @@ Review the complete replacement list. Approve interactively or rerun with
 manifest, or a non-empty migration target. Move or rename the structural
 conflict and retry.
 
+## OpenSpec global profile is incompatible
+
+Liftoff OpenSpec projects require profile `custom`, delivery `both`, and all 12
+OpenSpec 1.11 workflows. Review the observed and required values printed by
+Liftoff. Approve the separate interactive prompt or rerun the same command with
+`--configure-openspec-profile` only when the machine-wide change is intended.
+
+`--yes`, `--force`, `--install-tools`, and `--install-dependencies` do not
+authorize this change. If configuration or verification fails, run
+`openspec config list --json`, correct the reported OpenSpec issue, and retry
+before any project files are written.
+
+## OpenSpec wants to replace workflow files immediately
+
+A fresh Liftoff project should already contain all 12 workflows as skills and
+commands. Confirm that the same OpenSpec 1.11.0 binary, selected tools, global
+profile, delivery, and `githubCopilot.cloudAgent` choice are still in effect.
+
+For an older project, use:
+
+```bash
+openspec config profile
+openspec update
+```
+
+Select both delivery modes and every workflow. Do not use `liftoff update
+--force` to manage OpenSpec-owned skills or commands.
+
+## Copilot cloud-agent files are missing
+
+The GitHub-hosted coding agent is default-off and separate from Copilot in an
+editor or terminal. Opt in during new initialization with `--copilot-cloud`.
+For an existing project, set `githubCopilot.cloudAgent: true` in
+`openspec/config.yaml` and run `openspec update`. The expected files are
+`.github/workflows/copilot-setup-steps.yml` and
+`.github/agents/openspec.agent.md`.
+
 ## A handled write failed
 
 Liftoff reports whether rollback completed. Correct the filesystem problem and
@@ -81,6 +154,48 @@ hand-edited unsafe path.
 Commit or copy local work before overwriting. Transaction rollback protects a
 failed update, but Liftoff keeps no backup after success.
 
+For a new governance policy or launcher conflict, review that exact local file
+before considering `liftoff update --force`; do not delete it or activate remote
+governance merely to make update pass. The schema-v5 manifest records
+`handoff-partial` and no ownership entry for each preserved unrecorded conflict.
+Run `liftoff update --check` to inspect the remaining paths. Once each path is
+absent or matches the current artifact, plain update promotes the handoff to
+`handoff-generated`. Setting `governanceProfile` to `none` turns previously
+managed handoff files into preserved orphans rather than deleting them; an
+unrecorded conflicting file remains user-owned and is not reported as an
+orphan.
+
+## Governance handoff exists but nothing is enforced
+
+That is the expected initial state. The manifest records `handoff-generated`,
+not active enforcement. Commit and push the repository, run the selected-agent
+launcher, review its read-only Phase 0 report, and explicitly approve the plan
+before the agent creates a governance change.
+
+Missing licenses, a private Staging runner, alert routes, parallel deployment,
+or sufficient canary traffic must be reported as blockers or inapplicable
+controls. Do not replace them with duplicate scanners or placeholder success.
+
+Do not run an older Liftoff release to reverse a completed baseline migration.
+Restore the affected generated files and `liftoff.manifest.json` through version
+control, then reinstall from the restored locks.
+
+## A frozen Python install cannot reach the package index
+
+Keep the committed `pyproject.toml` and `uv.lock` unchanged and retry the
+generated `uv sync --frozen` command when registry connectivity is restored.
+Do not regenerate the lock as a connectivity workaround.
+
+Python Dockerfiles also accept a credential-free PEP 503 mirror while retaining
+the lock's exact versions and hashes:
+
+```bash
+docker build --build-arg UV_DEFAULT_INDEX=https://packages.example.test/simple/ .
+```
+
+Do not place credentials in build arguments. Configure authenticated registries
+through an approved secret-aware build mechanism.
+
 ## Power Apps dependencies or CLI are missing
 
 From the project root:

package/docs/workloads.md

@@ -7,12 +7,12 @@ prerequisites, generated artifacts, and maintenance checks that apply to it.
 
 | Workload | Primary choices | Required runtime | Liftoff-generated platform areas |
 | --- | --- | --- | --- |
-| GenAI application | Pattern, Azure region, environments, optional frontend | Python 3.12 and Node.js 20.19+ | API, orchestration, data, messaging, Docker, Azure OpenTofu |
-| API application | Python, Node.js, or Go API stack; Azure region; environments; optional frontend | Selected API runtime and Node.js 20.19+ | API, data, Docker, Azure OpenTofu |
-| Power Apps code app | Spec workflow, agents, optional Code Apps plugin | Node.js 22.12+ | Official React/Vite starter and project-local Power Apps tooling |
+| GenAI application | Pattern, Azure region, environments, optional frontend | Python 3.14, `uv` 0.12.7+, and Node.js 24.20+ | API, orchestration, data, messaging, Docker, Azure OpenTofu |
+| API application | Python 3.14, Node.js 24, or Go 1.27 API stack; Azure region; environments; optional frontend | Selected API runtime and Node.js 24.20+ | API, data, Docker, Azure OpenTofu |
+| Power Apps code app | Spec workflow, agents, optional Code Apps plugin | Node.js 24.20+ | Official React/Vite starter and project-local Power Apps tooling |
 
 All three workloads continue into the common OpenSpec or Spec Kit and coding
-agent flow.
+agent flow and the default local repository-governance handoff.
 
 ## GenAI application
 
@@ -29,11 +29,14 @@ The selected pattern fixes the API stack to Python, FastAPI, and PydanticAI.
 ### Generated output
 
 - FastAPI backend and Scalar/OpenAPI integration.
+- A committed `uv.lock` consumed through `uv sync --frozen`.
 - PydanticAI orchestration, prompts, and model configuration boundaries.
 - PostgreSQL and pattern-specific Redis or Azure Service Bus boundaries.
 - Offline-testable tracing and integration adapters.
 - Docker Compose and Azure OpenTofu.
 - Optional Vue frontend and pattern-specific Azure Functions workers.
+- Versioned repository-governance policy, workload context, guide, and
+  selected-agent launcher unless `none` is selected.
 
 ### Deferred actions
 
@@ -55,9 +58,12 @@ infrastructure before applying it.
 ### Generated output
 
 - Stack-native API, OpenAPI, tests, and database migrations.
+- Ecosystem-native locked metadata: `uv.lock`, `package-lock.json`, or
+  `go.mod` plus `go.sum`.
 - PostgreSQL, Redis, Azurite, and Mailpit local services where applicable.
 - Docker Compose and Azure OpenTofu.
 - Optional Vue frontend.
+- Versioned local repository-governance handoff unless explicitly disabled.
 
 ### Deferred actions
 
@@ -87,9 +93,12 @@ environment, API frontend, Docker, or OpenTofu selection.
 - React, Vite, TypeScript, Tailwind, and the Power Apps SDK and Vite plugin.
 - Locked root `package.json` and `package-lock.json`.
 - Project-local `power-apps` CLI supplied by the generated dependency graph.
-- `liftoff.config.json`, schema-v4 `liftoff.manifest.json`, starter provenance,
+- `liftoff.config.json`, schema-v5 `liftoff.manifest.json`, starter provenance,
   and third-party attribution.
 - Official OpenSpec or Spec Kit output and every selected agent marker.
+- The common local governance policy and selected-agent launcher, with backend,
+  container, OpenTofu, custom deployment, and API DAST controls marked
+  inapplicable.
 
 Liftoff does not create an API backend, `docker-compose.yml`,
 `infrastructure/`, API environments, or an environment-bound

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Interactive CLI for governed GenAI, API, and Power Apps code app projects.",
   "type": "module",
   "license": "GPL-3.0-only",
@@ -32,7 +32,9 @@
   "files": [
     "dist",
     "assets/locks",
+    "assets/governance",
     "assets/power-apps-code-app",
+    "assets/supported-stack.json",
     "docs",
     "README.md",
     "LICENSE"
@@ -45,25 +47,31 @@
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "audit:template-dependencies": "node scripts/audit-template-dependencies.mjs",
+    "refresh:supported-stack": "node scripts/refresh-supported-stack-baseline.mjs --write",
+    "check:supported-stack": "node scripts/refresh-supported-stack-baseline.mjs",
+    "check:supported-stack-freshness": "node scripts/check-supported-stack-freshness.mjs",
+    "canonicalize:python-locks": "node scripts/canonicalize-uv-lock.mjs assets/locks/python-standard/uv.lock assets/locks/python-genai/uv.lock",
     "refresh:power-apps-starter": "node scripts/refresh-power-apps-starter.mjs",
     "smoke:package": "npm run build && node scripts/package-smoke-test.mjs",
     "verify:standard-node-templates": "npm run build && node scripts/verify-standard-node-templates.mjs",
+    "verify:generated-containers": "npm run build && node scripts/verify-generated-containers.mjs",
     "verify:power-apps-starter": "npm run build && node scripts/verify-power-apps-starter.mjs",
     "verify:release-identity": "npm run build && node scripts/verify-release-identity.mjs",
     "verify:published": "npm run build && node scripts/verify-published-package.mjs",
-    "check": "npm run build && npm test"
+    "check": "npm run check:supported-stack && npm run build && npm test"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=24.20"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^20.14.10",
+    "@types/node": "^24.6.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.10.1",
+    "@inquirer/prompts": "^8.6.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "^1.1.1"
   }