@msn-control/liftoff 0.11.3 → 0.12.1

package/docs/repository-governance.md

@@ -14,17 +14,20 @@ cd my-project
 /liftoff-setup
 ```
 
-`/liftoff-setup` uses the deterministic Liftoff governance engine to complete
-the workflow-specific local bootstrap, then encounters the separately authorized
-publication and read-only Phase 0 boundaries. The user-owned activation state records
+The native setup integration uses the deterministic Liftoff governance engine to
+complete the workflow-specific local bootstrap and reviewed repairs, then
+coordinates separately authorized publication, cloud deployment, qualification,
+and enforcement. Codex invokes its native setup skill through the skill picker
+or `$skill-name`; it does not receive a fabricated slash-command adapter.
+The user-owned activation state records
 execution, not an agent's claim of completion.
 
-**Current activation limits:** local bootstrap is implemented, but the CLI does
-not yet wire every production phase executor or expose approval persistence
-and secure credential enrollment through the command-only setup flow. Missing
-capabilities stop with a blocker; they are not completed by assessment or by
-hand-editing evidence. See the [developer follow-up plan](../DEVELOPER.md#activation-completeness-and-separate-follow-up-plan)
-for the remaining activation work.
+**Independent milestones:** local readiness does not imply publication or
+deployment. Explicit local-only use and declining a later approval remain
+supported. Activation requires real source-matching provider evidence;
+unsupported account capabilities, unverified private access, and incomplete
+observations remain explicit blockers. Retained-state disposal is separate
+lifecycle work, not a 30-day delay before initial activation can complete.
 
 ## Managed files and user-owned state
 
@@ -39,8 +42,10 @@ Enabled governance adds managed-core files:
 .liftoff/governance/credential-policy.schema.json
 .github/prompts/liftoff-setup.prompt.md                # Copilot selected
 .claude/commands/liftoff-setup.md                      # Claude selected
+.agents/skills/liftoff-setup/SKILL.md                  # Codex selected
 .github/prompts/liftoff-governance-assess.prompt.md    # Copilot selected
 .claude/commands/liftoff-governance-assess.md           # Claude selected
+.agents/skills/liftoff-governance-assess/SKILL.md       # Codex selected
 ```
 
 Older generated setup aliases are retired. Use `liftoff update --force` after
@@ -167,7 +172,7 @@ normally return partial coverage. Exit 2 is advisory, not proof that governance
 is broken or permission to remediate.
 
 Reports go to stdout only, never activation state or evidence. Assessment cannot
-complete Phase 0, satisfy an approval gate, or advance any phase. The wrapper
+complete read-only Phase 0, satisfy an approval gate, or advance any phase. The wrapper
 explains the CLI's classifications without inventing findings or executing
 recommendations. Neither installing the integration nor running it activates,
 updates, upgrades, or migrates the project.
@@ -196,6 +201,7 @@ seed-valid
   -> pushed
   -> phase-0-complete
   -> activation-approved
+  -> bootstrap-workflow-source-ready
   -> credential-ready
   -> provider-ready
   -> state-path-selected
@@ -204,8 +210,10 @@ seed-valid
                             -> private-backend-proof    |
                             -> remote-import-verified --|
   -> remote-ready
-  -> application-foundation
+  -> application-prerequisites-ready
   -> workflow-source-ready
+  -> application-artifact-ready
+  -> application-foundation
   -> dev-proof
   -> staging-qualified
   -> production-rehearsed
@@ -213,7 +221,7 @@ seed-valid
   -> enforcement-approved
   -> rulesets-applied
   -> live-readback
-  -> bootstrap-state-disposed
+  ... separate lifecycle: bootstrap-state-disposed when due
 ```
 
 If policy prose, generated tasks, or an agent response orders a transition
@@ -254,8 +262,11 @@ requires cloud credentials. A failed local check remains unfinished; only
 explicit execution retries it after repair. Read-only status, resume, and
 verification do not advance tasks or rerun checks. Unchanged current proof can
 be reused; changed relevant inputs require fresh evidence.
-Recorded legacy-shared or unknown infrastructure layouts block this baseline
-with migration-required and no commands, even if new-looking directories exist.
+Recorded legacy-shared or unknown infrastructure layouts require a reviewed
+repair plan even if new-looking directories exist. Layout assessment reports
+migration-required and no commands are executed until approved. Use the setup integration's
+supported repair action; moving folders or editing manifest provenance is not
+a supported repair and does not prove that deployed state is safe to migrate.
 
 If the seed was already archived before setup began, it stays archived.
 Setup still runs the entire applicable local baseline, but strict OpenSpec
@@ -284,8 +295,11 @@ ask again; expanded resources, destinations, permissions, cost, exceptions, or
 destructive effects require a new approval.
 Its time window must satisfy `approvedAt <= now < expiresAt` and have a valid
 start/end interval. A future, reversed, or expired envelope cannot authorize
-execution. The contract does not imply a public approval-persistence workflow
-exists; an unavailable entry capability remains a blocker.
+execution. `governance plan` can preview dependency-ready work before approval.
+`governance approve --plan <fingerprint>` persists only the exact reviewed
+authority, with a separate project-bound user-local issue record. Imported
+project JSON is not permission. Final enforcement can bind both its approval
+and subsequent exact ruleset operations without granting other phase authority.
 
 ## Credentials for runner preflight
 
@@ -293,8 +307,7 @@ When `GITHUB_TOKEN` cannot read required hosted-runner metadata, setup first
 prefers an existing verified selected-repository GitHub App installation with the
 required read permissions. Liftoff does not install or broaden an App.
 
-If no approved App is available, the normative policy describes this
-fine-grained PAT fallback, not an implemented enrollment command:
+If no approved App is available, the narrowly scoped fallback is:
 
 | Field | Value |
 | --- | --- |
@@ -307,9 +320,11 @@ fine-grained PAT fallback, not an implemented enrollment command:
 | Writes | none |
 | Workflow/job allowlist | `.github/workflows/bootstrap-import-preflight.yml` job `bootstrap-import-preflight`; `.github/workflows/private-dast-preflight.yml` job `private-dast-preflight` |
 
-This release has no public masked credential-enrollment channel. Stop at the
-reported capability blocker rather than creating a credential or hand-writing
-state to make the phase pass.
+After reviewing and approving the credential-ready plan, use
+`liftoff governance credential-enroll --plan <fingerprint>`. The default input
+channel is a private TTY; `--protected-stdin` explicitly selects a protected
+automation channel. The published allowlisted workflow must prove actual
+credential use; the secret name or a policy file alone cannot establish readiness.
 Never paste or show the value in chat, argv, command arguments,
 logs, evidence, files, or screenshots. A disclosed value is
 compromised and must be revoked and rotated through its owner-controlled system.
@@ -323,7 +338,8 @@ secret value.
 
 Task checkboxes are a projection of phase state, not authority. Evidence
 documents carry repository identity, activation version vector, graph hash, phase
-contract digest, real input/baseline digests, body commitment, phase ID, timestamp,
+contract digest, scope, real input/baseline digests, reviewed before/after
+file and Git bindings, body commitment, phase ID, timestamp,
 producer, and result. The local execution anchor is separate from a verified
 remote repository binding; Phase 0 does not replace the anchor beneath earlier
 local receipts. Digests prove consistency, not an independent signature or
@@ -335,7 +351,11 @@ binds the full saved plan, including clocks. `bodyDigest` covers the payload and
 normalized readbacks. Consumers use the validated selected payload, not another
 raw record that happens to reuse an ID. Repository publication binds the actual
 reviewed push destination; Phase 0 cannot invalidate earlier local/publication
-receipts by replacing the local anchor.
+receipts by replacing the local anchor. Scoped projections keep later approved
+workflow publication from invalidating unrelated local application checks,
+while unplanned source, destination, and output changes still invalidate the
+affected proof. External operation handles and pre-write checkpoints prevent
+an interrupted workflow from being dispatched twice.
 
 There may be only one active governance source of truth. An unfinished bootstrap
 seed blocks Phase 0. Exactly one compatible active governance change is resumed.
@@ -348,21 +368,21 @@ Forced update can remove
 exact retired generated setup-alias entries from older manifests. When a policy,
 activation-contract, schema, or graph-hash change affects active work, status
 reports `reconciliation-required` and identifies affected descendants. Historical
-activation-v1 state and evidence remain byte-preserved and non-executable.
+activation-v1/v2 state and evidence remain byte-preserved and non-executable.
 `liftoff update --check` can preview an exact supported successor migration;
-explicitly approved apply preserves original history and creates linked v2 state.
+explicitly approved apply preserves original history and creates linked v3 state.
 Fresh local revalidation stops at unsupported or independently authorized work.
-Failure after commit leaves v2 blocked/resumable, not reset to v1. Never
+Failure after commit leaves v3 blocked/resumable, not reset to older authority. Never
 acknowledge an identity by editing JSON or treat old approvals as current consent.
 
 ## Private staging and bootstrap retention
 
-These are policy requirements for separately implemented production adapters,
-not a claim that this CLI can provision the complete platform.
 Private Staging DAST uses an ephemeral GitHub-hosted larger runner with Azure
 VNet injection only when genuinely applicable. Phase 0 discovers repository,
 subscription, authority, billing, network, DNS, cost, teardown, and capability
-facts read-only. If DAST is inapplicable, no runner networking is provisioned.
+facts read-only. DAST inapplicability does not bypass provider registration or
+the private execution path required for state operations. Existing suitable
+private paths are reused rather than replaced with public access.
 
 When a private ZRS backend cannot be reached and no existing private management
 path is approved, the bounded `bootstrap-local` branch may create only the
@@ -382,29 +402,37 @@ teardown.
 The generated setup integrations call only strict, project-aware CLI commands:
 
 ```bash
-liftoff governance status --json
-liftoff governance plan --json
-liftoff governance apply-next --json
-liftoff governance apply-next --json --execute
-liftoff governance resume --json
-liftoff governance verify --json
+liftoff governance status --scope local --json
+liftoff governance plan --scope local --json
+liftoff governance apply-next --scope local --json --execute
+liftoff governance verify --scope local --json
+liftoff governance plan --scope activation --inputs public-inputs.json --json
+liftoff governance approve --scope activation --plan <fingerprint> --json
+liftoff governance apply-next --scope activation --plan <fingerprint> --execute --json
+liftoff governance resume --scope activation --json
+liftoff governance status --scope lifecycle --json
 ```
 
-`status`, `plan`, and `verify` are read-only. `apply-next` previews mutations
+Direct commands default to activation scope. `status`, `resume`, and `verify`
+are read-only; `plan` saves a disclosed preview outside the repository without
+changing project/provider data. `apply-next` previews mutations
 unless `--execute` is supplied, and even then executes at most one graph-ready,
 evidence-ready, approved phase. Here, approved means its approval status is
 `not-required` or `reused`. Unknown subcommands, flags, or extra positionals
 fail before project discovery or mutation. Verification reports consistency
-separately from setup completion: a valid not-started or in-progress state may
+separately from selected-scope completion: a valid not-started or in-progress state may
 have `ok: true` and `verificationStatus: "consistent"` while `complete` remains
 false. An intact bootstrap seed awaiting baseline verification or archive is
 also incomplete rather than inconsistent. Missing or overlapping seeds, or an
 active seed contradicting recorded archive completion, still fail verification.
 
 Apply-next reports `selectedPhase` for the attempted transition and
-`executedPhase` only when execution succeeds (otherwise `null`). Its legacy
-`nextReadyPhase` field is not post-transition readiness; use the subsequent
-status or verify response for the next phase. OpenSpec failures include bounded
+`executedPhase` separately from recomputed post-transition `nextReadyPhase`.
+Schema-2 results also identify `nextPlannablePhase`, separate milestone progress,
+and structured registered `nextActions`. A pending external operation is not
+completed evidence. For failed or interrupted work, obtain a fresh
+`governance plan --recover-phase <phase>` and explicitly execute its reviewed
+`governance recover --plan <fingerprint> --execute` action. OpenSpec failures include bounded
 diagnostics with terminal controls removed; credential-shaped output is
 withheld rather than copied into state or command output.
 

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

@@ -9,8 +9,8 @@ Liftoff workload.
 
 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:
+isolated staging, passes every selected coding agent in stable order, and
+requires the complete custom profile with native-surface-aware `both` delivery:
 
 ```text
 propose, explore, new, continue, apply, update,
@@ -26,6 +26,9 @@ the machine-wide change.
 
 Generated projects contain `openspec/` plus all 12 official workflow skills and
 commands for each selected agent surface that supports them.
+Copilot and Claude receive all 12 skills and all 12 commands. Codex receives
+all 12 skills under `.agents/skills/openspec-<workflow>/SKILL.md`; it has no
+OpenSpec command adapter, so `both` does **not** require deprecated Codex prompts.
 
 ### Spec Kit
 
@@ -35,6 +38,11 @@ integration, and records the default separately from the full agent set.
 
 Generated projects contain `.specify/`, `specs/`, and the selected agent
 integration markers.
+The pinned native skill inventory is `analyze`, `clarify`, `constitution`,
+`implement`, `converge`, `plan`, `checklist`, `specify`, `tasks`, and
+`taskstoissues`. Codex uses `.agents/skills/speckit-<name>/SKILL.md`, with skills
+enabled by default and safe secondary installation. Copilot is installed with
+the official `--integration-options=--skills` option; Claude also uses skills.
 
 New projects also receive `specs/000-liftoff-bootstrap/spec.md`, `plan.md`, and
 `tasks.md`. These are explicit one-time, project-owned `seed` artifacts, separate
@@ -60,8 +68,12 @@ blocker. Adopting it requires separate reviewed project work; ordinary update,
 force, and assessment do not create seeds or infer earlier completion.
 
 Liftoff does not hand-write framework-owned core or integration output. It
-executes the tested official initializer, confines its writes to allowed roots,
-and validates the declared markers before merging.
+executes the tested official initializer and validates its complete declared
+native inventory before merging. New `.agents` output is accepted only at
+explicitly inventoried paths. Spec Kit's optional project-local
+`.codex/config.toml` event configuration is distinct from Codex's user-global
+account configuration. Custom neighboring skills and unrelated configuration
+remain outside the write inventory; unsafe links and case collisions block it.
 
 ## Select coding agents
 
@@ -69,7 +81,12 @@ Liftoff supports:
 
 - GitHub Copilot.
 - Claude Code.
-- Both agents together.
+- OpenAI Codex.
+- Any nonempty combination of the three agents (all seven subsets).
+
+The canonical IDs and order are `github-copilot`, `claude`, `codex`. The CLI
+also accepts `copilot` for GitHub Copilot, and normalizes aliases and duplicates
+without adding unselected agents.
 
 On a real TTY, use the arrow keys to move, Space to mark or unmark an agent,
 and Enter to confirm. At least one agent is required.
@@ -78,24 +95,106 @@ When standard input is redirected, the deterministic fallback accepts a
 comma-separated value such as:
 
 ```text
-copilot,claude
+copilot,claude,codex
 ```
 
 Noninteractive commands use:
 
 ```bash
---agents copilot,claude
+--agents copilot,claude,codex
 ```
 
-Spec Kit additionally requires `--default-agent copilot` or
-`--default-agent claude` when both are selected. OpenSpec does not record a
-default agent.
+Spec Kit additionally requires exactly one selected default when multiple agents
+are selected: `--default-agent copilot`, `--default-agent claude`, or
+`--default-agent codex`. Secondary installation never changes that default.
+For example, `--spec spec-kit --agents copilot,codex --default-agent codex`.
+OpenSpec does not record a default agent. `--agents codex` works alone with
+either framework and does not require Copilot or Claude.
+
+## Native setup and assessment
+
+For governed projects, initialization is followed by the selected agent's native
+setup entry point:
+
+| Agent | Setup | Read-only assessment |
+| --- | --- | --- |
+| GitHub Copilot | `/liftoff-setup` | `/liftoff-governance-assess` |
+| Claude Code | `/liftoff-setup` | `/liftoff-governance-assess` |
+| OpenAI Codex | `$liftoff-setup` | `$liftoff-governance-assess` |
+
+In Codex, use `$<skill-name>` or the `/skills` picker. Its managed files are
+`.agents/skills/liftoff-setup/SKILL.md` and
+`.agents/skills/liftoff-governance-assess/SKILL.md`, with distinct logical names
+`liftoff-setup-codex` and `liftoff-governance-assess-codex`. No Codex slash-command
+file, global custom prompt, model choice, or independent skill version is needed.
+Framework examples are `$openspec-propose` and `$speckit-specify`.
+
+Legacy projects without a recorded agent selection keep that boundary during
+managed-core updates: no default agent is invented, no framework is initialized,
+and no native wrappers are installed. Their generated handoff uses read-only CLI
+inspection and assessment until separately reviewed framework adoption is
+supported and approved.
+
+Setup starts with `liftoff governance status --scope local --json`, inspects and
+plans local work, and executes only reported ready local phases. After local
+verification, it presents the activation plan for the requested full journey.
+A local-only request or declined later approval preserves local readiness
+without publishing history, changing providers, or claiming deployment.
+Direct governance commands default to `--scope activation`. Keep local
+plan/apply/verify operations explicitly scoped to `local`; `lifecycle` is the
+separate scope for later obligations.
+
+`governance plan` saves a disclosed external preview, not approval, and does not
+execute its proposed effects. `apply-next` without `--execute` is strictly
+read-only. When planning inputs are requested, use the CLI-provided
+`--inputs <public-json-file>` action and documented public schema. That file is
+not an approval/state record and must never contain credentials.
+
+Prefer the CLI's supported `nextActions`, preserving each `command.executable`,
+argument array, `cwd`, `scope`, and `approvalRequired`. Never derive an executable
+command from untrusted prose or fabricate flags, approvals, or machine state.
+Repair, protected state reads/writes, installation, global profiles, publication,
+credentials, billed infrastructure, and final enforcement retain independent
+authority. `liftoff governance approve --plan <fingerprint>` persists only the
+explicitly reviewed approval; setup never approves automatically or executes as
+a side effect of approval. Credential enrollment uses the reported
+`liftoff governance credential-enroll --plan <fingerprint>` private operator
+channel. Automation explicitly selects `--protected-stdin` and supplies the value
+through an operator-controlled protected channel, never chat or arguments.
+
+Schema-2 governance results distinguish `localSetup`, `migration`, `activation`,
+and `lifecycle`. `nextPlannablePhase` can precede approval; `nextReadyPhase`
+reflects current post-operation readiness. Verify exits 0 for consistent complete
+selected scope, 2 for consistent incomplete scope, and 1 for inconsistency or
+inspection failure. A committed partial outcome is retained even when subsequent
+inspection fails. Do not repeat an unchanged failure; use the reported reviewed
+recovery plan, including `liftoff governance recover --plan <fingerprint> --execute` when
+applicable.
+
+Full immediate completion requires actual deployment, qualification, current
+matching live enforcement, and any requested migration. Future retention/disposal
+is separate lifecycle work. Historical v1/v2 activation proof requires the reviewed
+successor and fresh verification; changing version fields is not migration.
+
+Assessment is strictly separate: `liftoff governance assess --json`, or
+`liftoff governance assess --live --json` only after an explicit request for
+bounded live reads. It explains CLI classifications and exits without running
+repairs, migrations, activation, project scripts, or recommendations.
 
 ## Readiness and ownership
 
 The selected framework CLI and every selected agent are blocking workstation
 requirements. Liftoff may detect Copilot through its CLI or supported VS Code
-extensions. Claude Code is checked through version and health probes.
+extensions. Claude Code is checked through version and health probes; Codex uses
+its registered `codex` executable. Compatible official stable and preview coding
+agents satisfy readiness, with preview notices. A newer available release alone
+does not block setup, and runtime/framework constraints are not relaxed.
+
+Framework execution uses isolated `HOME`, `USERPROFILE`, XDG configuration/data/
+cache paths, and `CODEX_HOME`. Only the approved public OpenSpec profile fields
+needed for rendering are seeded. Real global prompts, account settings, and
+unrelated user files are not copied or cleaned. Selecting Codex, approving a
+project plan, or passing `--yes` is not global-profile consent.
 
 Framework files remain owned by the official initializer. Liftoff validates
 them but excludes framework-owned output from durable artifact hashes so a
@@ -113,11 +212,31 @@ Plain `liftoff update` intentionally does not regenerate these framework-owned
 files.
 
 Repository-governance launchers are separate managed-core Liftoff files at the exact
-Copilot prompt and Claude command paths documented in
+Copilot prompt, Claude command, and Codex skill paths documented here and in
 [repository governance](repository-governance.md). They reference one canonical
 policy and context rather than duplicating framework-owned content. Later
 governance changes are distinct from the exact bootstrap seed. The setup kernel
-does not invent an active change, approval, or missing production executor.
+does not invent an active change, approval, or execution proof.
+
+### Add an agent to an existing project
+
+Do not reinitialize the application or edit its manifest to claim an integration:
+
+```bash
+liftoff repair --check --add-agents codex --json
+```
+
+Review the exact project-bound plan, then approve its displayed fingerprint.
+For Spec Kit, add `--default-agent codex` to the preview only when you explicitly
+want that default change. Existing agents/defaults, custom skills, and shared
+templates remain preserved outside the reviewed scope. Adding a recorded agent
+with missing native markers repairs those markers rather than becoming a false
+no-op. Agent removal and workflow switching are not additive repairs.
+
+Tool/dependency installation and global OpenSpec profile configuration remain
+separate permissions during repair. A stateful infrastructure blocker is not
+automatically added to an agent-only write plan. Ordinary `liftoff update`
+continues to maintain only its declared managed-core/identity-migration scope.
 
 Install the exact selected framework release with its supported package manager:
 

package/docs/troubleshooting.md

@@ -26,12 +26,42 @@ npm install -g @msn-control/liftoff@latest
 
 ## 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
+Automatic replacement supports the canonical package at npm's effective
+global package root or an independently verified standard Homebrew prefix on
+macOS. 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.
 
+### Homebrew Node and npm report a different prefix
+
+A Homebrew Node installation can report a versioned Cellar global root while
+Liftoff remains installed under `/opt/homebrew/lib/node_modules` (Apple Silicon)
+or `/usr/local/lib/node_modules` (Intel). This is an installation-prefix mismatch,
+not a project-directory or PATH-refresh problem.
+
+The patched upgrader verifies the running package, matching Homebrew Node/npm
+layout, and global launcher before targeting the existing prefix. Registry
+checks, installation, and replacement verification retain that target. It
+neither installs another copy in the Cellar nor edits `.npmrc`. If prefix-specific
+registry settings differ, `registry_prefix_mismatch` blocks the operation rather
+than silently bypassing a managed mirror.
+
+Older binaries, including 0.11.3 and 0.12.0, still need the one-time workaround.
+Only after confirming that `liftoff` resolves under `/opt/homebrew/lib/node_modules`,
+run:
+
+```bash
+npm_config_prefix=/opt/homebrew liftoff upgrade --check
+npm_config_prefix=/opt/homebrew liftoff upgrade
+liftoff --version
+```
+
+For a verified Intel Homebrew installation use `/usr/local` instead. The
+environment assignment applies only to that invocation. Do not use it to force
+replacement of a local, linked, or unrelated installation. Keep your approved
+registry policy; a blocked mirror still requires its owner's intervention.
+
 ## CLI upgrade is blocked by a stale managed registry
 
 Canonical npm defines the exact stable target, but Liftoff installs through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msn-control/liftoff",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "description": "Interactive CLI for governed GenAI applications and APIs.",
   "type": "module",
   "license": "GPL-3.0-only",