@msn-control/liftoff 0.10.3 → 0.11.1

package/docs/getting-started.md

@@ -1,18 +1,19 @@
 # Getting started
 
-Liftoff is an interactive project initializer for governed GenAI applications,
-standard APIs, and Power Apps code apps.
+Liftoff is an interactive project initializer for governed GenAI applications
+and standard APIs.
 
 ## 1. Install the CLI
 
-Liftoff and generated Node.js workloads require Node.js 24.20 or newer.
-Python workloads use Python 3.14 with frozen `uv` dependency locks.
+Workstation readiness requires stable Node.js 24 LTS at 24.20.0 or newer within
+that line, plus npm 12.x at 12.0.2 or newer when selected tools need it.
+Python workloads use Python 3.14.x with frozen `uv` dependency locks.
 
 The canonical release registry is `https://registry.npmjs.org`:
 
 ```bash
-npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org
-npm install -g @msn-control/liftoff@latest --registry=https://registry.npmjs.org
+npm view @msn-control/liftoff@latest version --registry=https://registry.npmjs.org --@msn-control:registry=https://registry.npmjs.org
+npm install -g @msn-control/liftoff@latest
 liftoff --version
 ```
 
@@ -22,6 +23,10 @@ If your organization requires a managed npm registry, query
 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.
+The read-only canonical query isolates both default and scoped registry
+overrides. Installation intentionally honors the configured
+`@msn-control:registry` before the default registry; do not force a canonical
+download around an organization's delivery policy.
 
 Versions predating the self-upgrade command require that manual global install
 once. After a capable version is installed globally with npm, use:
@@ -50,7 +55,7 @@ cd my-project
 
 The guided flow asks for:
 
-1. Project identity and workload: GenAI, API, or Power Apps code app.
+1. Project identity and workload: GenAI or API.
 2. Only the architecture choices applicable to that workload.
    For GenAI, **I'm not sure yet - Generic GenAI starter** is the safe default
    when no specialization has been selected.
@@ -62,8 +67,7 @@ The guided flow asks for:
 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
+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
@@ -74,12 +78,12 @@ and asks separately before staging.
 
 When governance is enabled, `/liftoff-setup` is the next selected-agent action.
 It has no model-selection requirement: safety comes from the Liftoff CLI phase
-graph, local evidence, approval envelopes, and readback. Setup first completes,
-syncs, and archives the generated `bootstrap-<project>` seed. Only then does it
-reach explicit authority gates for repository commit/push, credentials, billed
-infrastructure or policy exceptions, final enforcement, destructive cleanup, and
-external blockers. Commit and push are never implicit in `liftoff init`, `--yes`,
-or read-only checks.
+graph, local evidence, approval envelopes, and readback. OpenSpec setup completes,
+syncs, and archives `bootstrap-<project>`; Spec Kit validates and finalizes
+`specs/000-liftoff-bootstrap/` locally. Neither workflow invents completed product
+work. Missing approval-persistence, credential-enrollment, and production phase
+executors remain specific blockers. Commit and push are never implicit in
+`liftoff init`, `--yes`, or read-only checks.
 
 For deterministic generic generation, use `--type genai --pattern generic`.
 
@@ -97,26 +101,35 @@ non-empty target.
 
 ## 4. Local baseline setup verifies
 
-`/liftoff-setup` runs only local, project-applicable baseline checks before it
-archives the seed:
+`/liftoff-setup` runs only local, project-applicable baseline checks before
+archiving the OpenSpec seed or finalizing the Spec Kit bundle. Commands run in
+their declared component directories, not all from an arbitrary working directory:
 
 ```bash
 liftoff validate
 # backend tests from the generated README when a backend exists
 # frontend build from the generated README when a frontend exists
 docker compose config -q
+# From infrastructure/opentofu/azure/:
 tofu fmt -check -recursive
+# Within each selected environments/<environment>/ infrastructure root:
 tofu init -backend=false
 tofu validate
-openspec validate --strict
+# OpenSpec only, from the project root (replace the generated change name):
+openspec validate bootstrap-my-project --strict
 ```
 
-Absent components are inapplicable: a Power Apps project does not fabricate
-backend, Docker, or OpenTofu success, and an API project without a frontend skips
-frontend build evidence. The baseline does not run `tofu plan`, `tofu apply`,
+Absent optional components are inapplicable: an API project without a frontend
+skips frontend build evidence. The baseline does not run `tofu plan`, `tofu apply`,
 start containers, deploy, mutate GitHub, or require cloud credentials. If a check
-fails, the seed remains active and `/liftoff-setup` resumes idempotently after
-you fix the blocker; verified phases are not repeated.
+fails, the seed remains unfinished. After repair, explicit execution can retry
+the local baseline; read-only `resume` does not run it. Current unchanged proof
+can be reused, while changed inputs require new evidence.
+Dependencies must already be usable, or separately installed with explicit
+consent; passing a baseline does not prove that installation or consent happened.
+Spec Kit's B001–B006 projection is finalized only after its checks pass.
+Legacy/shared or unknown infrastructure layouts block baseline execution with a
+migration-required result rather than omitting those checks.
 
 You can run read-only maintenance at any time:
 
@@ -132,14 +145,14 @@ liftoff governance verify --json
 adds read-only workstation, runtime, authentication, dependency,
 workload-specific, and governance-state diagnostics.
 
-After setup archives the seed and you explicitly approve repository publication,
-normal development follows your selected workflow:
+After the local bootstrap handoff, normal development follows your selected
+workflow. Repository publication and production activation remain separate:
 
 - GenAI and API projects: copy `.env.example` to `.env`, install the generated
   stack dependencies, then use `liftoff dev` and `liftoff infra` to print local
-  development and infrastructure commands.
-- Power Apps projects: run `npm ci`, then `npm run dev`. Environment binding,
-  connector addition, and `power-apps push` are deliberately deferred.
+  development and infrastructure commands. Native Go also copies
+  `runtime.config.example.json` to `runtime.config.json`; see the
+  [stack-specific configuration recipes](configuration-and-manifests.md#application-runtime-configuration).
 - OpenSpec or Spec Kit changes drive normal feature work; release and hotfix
   flows follow the governed GitFlow plan after activation evidence is green.
 
@@ -151,7 +164,7 @@ Use `liftoff plan` to resolve choices and preview requirements without writing
 files or running installers:
 
 ```bash
-liftoff plan --type power-apps-code-app --spec openspec --agents copilot
+liftoff plan --type standard --api node --spec openspec --agents copilot
 ```
 
 Automation can pass the same options to `liftoff init`. Use `--yes` for project
@@ -176,5 +189,5 @@ source remains byte-for-byte unchanged.
 liftoff migrate ../legacy-app --region eastus --agents copilot,claude --yes
 ```
 
-Power Apps migration from an arbitrary existing application is not part of the
-current workload contract.
+Power Apps support is retired, including existing-project maintenance. Retired
+inputs are rejected without converting or deleting the original application.

package/docs/prerequisites.md

@@ -1,18 +1,26 @@
 # Prerequisites
 
 Liftoff derives workstation and project requirements from the complete resolved
-plan. A Power Apps project is not asked to install API or infrastructure tools,
-and a Go API is not asked to install Python.
+plan. A Go API does not inherit Python backend dependencies, although a selected
+framework such as Spec Kit can require Python for its own tooling.
 
 ## Baseline
 
-- 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.
+- Workstation Node.js: stable Node.js 24 LTS, version 24.20.0 or newer within 24.x.
+- npm-dependent stacks or OpenSpec: stable npm 12.x, version 12.0.2 or newer.
+- Python projects: stable Python 3.14.x and `uv` 0.12.x at version 0.12.7 or newer.
+- Go projects: stable Go 1.27.x.
+- Generated Azure infrastructure: stable OpenTofu 1.12.x at version 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.
 
+Minimum versions do not authorize a different, untested release line. Release
+candidates and other prereleases do not satisfy stable floors or exact framework
+pins. A working Node.js executable does not establish npm readiness: when npm is
+required, it is probed separately before destination writes. A missing npm
+executable requires a separately reviewed machine-level repair; Liftoff does not
+try to run the missing executable or reinstall Node.js on its behalf.
+
 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,
@@ -27,6 +35,8 @@ runtime. GenAI uses Python 3.14 and the Python/FastAPI/PydanticAI stack.
 Blocking checks must be ready before initialization can safely complete:
 
 - Required runtime and minimum version.
+- Required package managers, including npm for Node.js dependencies, a frontend,
+  or OpenSpec.
 - Selected spec framework CLI.
 - Every selected coding agent.
 - For OpenSpec, global profile `custom`, delivery `both`, and all 12 workflows.
@@ -36,7 +46,6 @@ Advisory checks describe useful but deferrable capabilities:
 - Docker CLI and daemon health for API workloads.
 - OpenTofu for generated Azure infrastructure.
 - Azure CLI and observable authentication health.
-- Optional Code Apps plugin state for Power Apps.
 
 Authentication checks are read-only. Liftoff never stores credentials or signs
 in to a cloud or agent on your behalf.
@@ -63,7 +72,7 @@ can register each missing namespace explicitly before dependent resources.
 without writing files or running installers:
 
 ```bash
-liftoff plan --type power-apps-code-app --spec openspec --agents copilot,claude
+liftoff plan --type standard --api node --spec openspec --agents copilot,claude
 ```
 
 ## Tool installation consent
@@ -103,19 +112,22 @@ Project-local dependency setup is separate from workstation tools and requires
 `--install-dependencies` or interactive approval after a successful project
 merge.
 
-For Power Apps, Liftoff runs only the root locked install:
-
-```bash
-npm ci
-```
-
-The generated `package.json` and `package-lock.json` are validated before
-installation and protected from installer mutation. If dependency setup is
-skipped or fails, Liftoff prints the exact resume command rather than claiming
-the project is ready.
-
 GenAI and API projects use their generated stack-native locked dependency
-commands.
+commands. If dependency setup is skipped or fails, Liftoff prints the exact
+resume command rather than claiming the project is ready.
+
+Recovery output identifies its shell: POSIX shell on macOS/Linux and PowerShell
+on Windows. Copy the command into that shell; directory names and arguments are
+quoted literally rather than expanded as environment variables.
+
+If protected metadata changes during dependency setup, Liftoff stops and lists
+the changed paths. It preserves those edits instead of assuming the installer
+caused them and restoring older bytes over concurrent work. Review and repair
+the metadata before retrying. Dependency scripts can also change other project
+files; this check is not a script sandbox.
+Dependencies that are already installed and usable do not need a new install
+merely to satisfy a bootstrap checkbox. Local checks prove usability, not that
+an installation or its consent occurred.
 
 Python projects use the generated lock without resolving new versions:
 
@@ -130,24 +142,11 @@ 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.
-Liftoff checks it without downloading another package:
-
-```bash
-npx --no-install power-apps --version
-```
-
-If `node_modules` is absent, run `npm ci` first. Environment binding and cloud
-authentication remain separate later actions.
-
 ## Agent detection
 
 Copilot can be detected through its CLI or supported VS Code extensions.
 Claude Code is checked with its version and doctor commands. When both are
 selected, both must be ready.
 
-The optional Code Apps plugin uses independent, read-only probes for each
-selected agent. A missing executable, timeout, or unsupported plugin-list
-result is reported as not observable rather than silently treated as missing.
+Power Apps and Code Apps plugin preparation are retired. Their inputs are
+rejected before selecting or installing a former workload-specific tool set.

package/docs/project-structure.md

@@ -17,7 +17,9 @@ project/
 |-- liftoff.config.json
 |-- liftoff.manifest.json
 |-- .env.example
+|-- runtime.config.example.json # Go native configuration only
 |-- Dockerfile
+|-- .dockerignore
 |-- docker-compose.yml
 |-- .liftoff/
 |   `-- governance/             # managed-core local handoff when enabled
@@ -45,14 +47,18 @@ project/
 |-- infrastructure/
 |   `-- opentofu/
 |       `-- azure/
-|           `-- .terraform.lock.hcl
+|           |-- modules/application/
+|           `-- environments/<env>/ # independent root, <env>.tfvars and provider lock
 |-- openspec/ or .specify/
+|-- specs/000-liftoff-bootstrap/ # Spec Kit only: one-time spec.md, plan.md, tasks.md
 |-- .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-setup.prompt.md
 |   or .claude/commands/liftoff-setup.md
+|-- .github/prompts/liftoff-governance-assess.prompt.md
+|   or .claude/commands/liftoff-governance-assess.md
 |-- frontend/                  # only when selected
 |-- functions/<worker-name>/  # only for worker-enabled GenAI patterns
 `-- migration/legacy/         # only after liftoff migrate
@@ -62,7 +68,9 @@ project/
 
 - `backend` contains the selected API stack and Scalar/OpenAPI wiring. Python
   uses `backend/apis`, Node.js uses `backend/src`, and Go uses
-  `backend/cmd/api` plus `backend/internal`.
+  `backend/cmd/api` plus `backend/internal`. Node includes an explicit
+  `backend/vitest.config.ts`; Go's `backend/cmd/migrate/main.go` passes resolved
+  configuration to the existing pinned Goose migration tool.
 - `backend/orchestration` appears only in GenAI projects and contains
   PydanticAI agents, prompts, model configuration, and integration boundaries.
   The generic pattern creates `generic_agent.py`, `generic.md`, and the neutral
@@ -78,8 +86,12 @@ project/
 - 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.
+- `infrastructure/opentofu/azure/modules/application` contains the shared module.
+  Each selected `infrastructure/opentofu/azure/environments/<env>` root owns its
+  named tfvars, provider lock, and independent local/remote state configuration.
+  Existing shared-state projects are not relocated by update or force.
+  The eight [retired flat-root identities](azure-deployment.md#explicit-flat-root-identity-retirement)
+  remain historical provenance; new root-looking files do not establish eligibility.
 - `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
@@ -88,6 +100,9 @@ project/
 - `/liftoff-setup` is generated when repository governance is enabled. It calls
   `liftoff governance status|plan|apply-next|resume|verify` and has no model
   selection or separate setup-skill version.
+- `/liftoff-governance-assess` is a separate selected-agent, read-only wrapper
+  around `liftoff governance assess --json`. It is local-only unless live reads
+  are explicitly requested; it never runs automatically or replaces setup.
 
 ### Conditional areas
 
@@ -99,53 +114,36 @@ project/
   separate from Azure Functions runtime files.
 - `migration/legacy` contains the filtered source copy created by migration.
 
-## Power Apps code app
+### Runtime configuration and image boundaries
 
-```text
-project/
-|-- README.md
-|-- THIRD_PARTY_NOTICES.md
-|-- liftoff.config.json
-|-- liftoff.manifest.json
-|-- package.json
-|-- package-lock.json
-|-- index.html
-|-- vite.config.ts
-|-- eslint.config.js
-|-- tsconfig.json
-|-- public/
-|-- src/
-|   |-- App.tsx
-|   |-- main.tsx
-|   |-- router.tsx
-|   |-- components/
-|   |-- hooks/
-|   |-- pages/
-|   `-- providers/
-|-- .liftoff/governance/        # managed-core setup files when enabled
-|-- governance/                 # user-owned activation state after setup starts
-`-- openspec/ or .specify/
-```
+Python and Node.js native startup read the project-root `.env`; process
+environment values take precedence over file-backed settings and nonsecret
+defaults. Go native startup from `backend/` reads `../runtime.config.json`;
+copy `runtime.config.example.json` to that path or select explicit JSON with
+`LIFTOFF_ENV_FILE`. It does not shell-source `.env`. Configuration is resolved
+once per process; restart after editing the selected file.
+Explicit missing, unreadable, or malformed selected files fail before fallback.
+See [configuration syntax and native commands](configuration-and-manifests.md#application-runtime-configuration)
+for strict dotenv quoting and Go's string-valued JSON contract.
 
-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-state.json`, approvals, evidence, credentials, and
-supersession records remain user-owned and are not listed as managed artifacts.
+Compose passes applicable runtime settings explicitly while keeping PostgreSQL,
+Redis, and other generated service addresses container-reachable. Root and
+frontend `.dockerignore` files exclude host virtual environments, `node_modules`,
+build outputs, VCS metadata, state, and local secrets. Installing dependencies
+locally must not copy a host environment over dependencies installed in an image.
 
-This root follows the pinned official Microsoft starter. It includes the
-Power Apps SDK, Vite plugin, and project-local CLI through locked npm
-dependencies.
+## Retired project layouts
 
-Liftoff intentionally does not generate `backend/`, `database/`,
-`docker-compose.yml`, `environments/`, `infrastructure/`, or
-`power.config.json` for this workload.
+Power Apps code app generation and maintenance are retired. An existing
+Power Apps manifest is rejected without converting its root layout or modifying
+application, framework, dependency, or governance files. The remaining generated
+layouts are the API and GenAI layouts above.
 
 ## Managed versus user-owned governance artifacts
 
 `liftoff.manifest.json` v7 records managed-core hashes for the governance policy,
 context, guide, phase graph, compatibility metadata, credential-policy schema,
-and setup integrations. `liftoff update` may reconcile only those managed-core
+and setup and assessment integrations. `liftoff update` may reconcile only those managed-core
 paths. Forced update may remove exact retired generated setup-alias ownership
 from older manifests after review. It preserves user-owned activation state,
 immutable evidence, approvals, credential policies, active OpenSpec changes, and
@@ -164,12 +162,12 @@ success-shaped placeholders:
   invocation fails clearly.
 - Redis Streams uses `REDIS_URL` and `REDIS_STREAM_NAME`.
 - Azure Service Bus uses `SERVICE_BUS_QUEUE_NAME` and either
-  `SERVICE_BUS_CONNECTION_STRING` or
-  `SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE`; `AZURE_CLIENT_ID` selects a
-  user-assigned managed identity.
+  `SERVICE_BUS_AUTH_MODE=connection-string` with `SERVICE_BUS_CONNECTION_STRING`,
+  or `managed-identity` with `SERVICE_BUS_FULLY_QUALIFIED_NAMESPACE` and
+  `AZURE_CLIENT_ID` for the selected user-assigned identity.
 - Langfuse requires both `LANGFUSE_PUBLIC_KEY` and
-  `LANGFUSE_SECRET_KEY`, with optional `LANGFUSE_HOST`. Without both keys,
-  tracing is explicitly disabled.
+  `LANGFUSE_SECRET_KEY`, with optional `LANGFUSE_HOST`. Both blank disables
+  tracing; only one configured key is an error.
 - Frontends read `VITE_API_BASE_URL`, call the route selected by the pattern or
   API stack, and expose loading, response, and failure states.
 - Backends allow the local frontend origin by default.