@chllming/wave-orchestration 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 0.9.4 - 2026-04-05
+
+- Laddered gate modes: bootstrap/standard/strict per wave number
+- Bootstrap pass: exit 0 + deliverables exist = advance (no QA signals needed)
+- Fix: requireDocumentationStewardFromWave threshold strictly respected
+- New config: gateModeThresholds, bootstrapPassConditions, testCommand
+- evaluateBootstrapGate() and resolveGateMode() functions
+
+## 0.9.3 - 2026-03-30
+
+### Fixed And Hardened
+
+- WAVE_GATE_REGEX now accepts gap alongside pass|concerns|blocked for all five gate dimensions (architecture, integration, durability, live, docs). Previously, agents that reported a documented gap (e.g. live=gap for an infrastructure topology constraint) had their marker rejected entirely, causing missing-wave-gate failures that prevented wave closure.
+- validateContQaSummary now treats gap dimension values as a conditional pass (ok: true, statusCode: conditional-pass) instead of a hard blocker, with detail text listing which dimensions have documented gaps.
+- The cont-QA coordination prompt now documents gap as a valid dimension value alongside pass|concerns|blocked.
+
+### Added
+
+- First-time wave launch now auto-triggers wave project setup when no project profile exists, matching existing wave draft behavior. (Contributed by @justanothernate in #54)
+- wave project setup now shows descriptive help text before each prompt, explains all template and posture options inline, and adds whitespace between question groups for readability. (Contributed by @justanothernate in #54)
+- PromptSession gains a describe(text) method for writing contextual help to stderr during interactive setup flows.
+- parseArgs now passes the loaded config object through to runLauncherCli, avoiding a redundant loadWaveConfig() call.
+
+### Testing And Validation
+
+- `pnpm exec vitest run --config vitest.config.ts`
+- `node scripts/wave.mjs doctor --json`
+- `node scripts/wave.mjs launch --lane main --dry-run --no-dashboard`
+- `pnpm test -- test/wave-orchestrator/release-surface.test.ts`
+
 ## 0.9.2 - 2026-03-29
 
 ### Added

package/README.md

@@ -107,19 +107,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.9.2`
-- Release tag: [`v0.9.2`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.2)
+- `@chllming/wave-orchestration@0.9.4`
+- Release tag: [`v0.9.4`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.4)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.9.2`:
+Highlights in `0.9.4`:
 
-- Live agent execution now uses detached process runners by default, which reduces tmux churn and memory pressure during wider orchestration bursts. Tmux is now optional and dashboard-only.
-- The sandbox-safe runtime path is now `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach`, which behaves better under short-lived exec clients such as LEAPclaw, OpenClaw, and Nemoshell.
-- Supervisor recovery, launcher progress journaling, and exact-context reads are now hardier for multi-wave runs, reruns, and daemon/client loss in containerized or sandboxed environments.
-- Owned Wave Control deployments now support Stack-authenticated browser access, Wave-managed approval states and provider grants, personal access tokens, dedicated service tokens, encrypted per-user credential leasing, and the separate `services/wave-control-web` operator frontend.
-- Corridor is now documented as a first-class security input: it can run direct or through an owned Wave Control broker, materialize per-wave security context on implementation-owned paths, and block closure before integration when fetches fail or matched findings cross the configured threshold.
-- Release docs, migration guidance, runtime-config and closure references, Wave Control docs, the new Corridor reference, the manifest, and the tracked install-state fixtures now all point at the `0.9.2` surface.
+- Wave-gate markers now accept `gap` alongside `pass`, `concerns`, and `blocked` for all five gate dimensions. Agents that report a documented gap (e.g. `live=gap` for an infrastructure topology constraint) no longer have their marker rejected entirely, and `cont-QA` treats gap values as a conditional pass instead of a hard blocker.
+- First-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, matching existing `wave draft` behavior. The interactive setup flow now shows descriptive help text, explains all template and posture options inline, and adds whitespace between question groups for readability.
+- `PromptSession` gains a `describe(text)` method for writing contextual help to stderr during interactive setup flows.
+- `parseArgs` now passes the loaded config object through to `runLauncherCli`, avoiding a redundant `loadWaveConfig()` call.
+- Release docs, migration guidance, runtime-config and closure references, the manifest, and the tracked install-state fixtures now all point at the `0.9.4` surface.
 
 Requirements:
 

package/docs/README.md

@@ -38,7 +38,7 @@ The useful path is journey-first:
 - Setting up multiple projects in one monorepo:
   Read [guides/monorepo-projects.md](./guides/monorepo-projects.md) for `defaultProject`, `projects.<projectId>`, project-scoped state paths, and telemetry defaults.
 - Adding an optional pre-implementation design steward:
-  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.9.2` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
+  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.9.3` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
 - Running in LEAPclaw, OpenClaw, Nemoshell, Docker, or another short-lived sandbox:
   Read [guides/sandboxed-environments.md](./guides/sandboxed-environments.md) first for the submit or supervise pattern, persistent-state expectations, and dashboard guidance, then use [plans/sandbox-end-state-architecture.md](./plans/sandbox-end-state-architecture.md) for the deeper runtime design.
 - Want signal-driven automation or long-running watcher loops:
@@ -53,8 +53,8 @@ The useful path is journey-first:
   Read [plans/migration.md](./plans/migration.md), then review the release notes in [../CHANGELOG.md](../CHANGELOG.md) before running `pnpm exec wave upgrade`.
 - Publishing the package:
   Read [reference/package-publishing-flow.md](./reference/package-publishing-flow.md) for the end-to-end release path, the GitHub publish workflows, the lifecycle scripts, and the verification or repair flow.
-- Want the practical `0.9.2` operating stance:
-  Read [guides/recommendations-0.9.2.md](./guides/recommendations-0.9.2.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
+- Want the practical `0.9.3` operating stance:
+  Read [guides/recommendations-0.9.4.md](./guides/recommendations-0.9.4.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
 - Want the concrete runtime module map:
   Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
 - Want the CLI surface map:

package/docs/guides/recommendations-0.9.3.md

@@ -0,0 +1,137 @@
+---
+title: "0.9.3 Recommendations"
+summary: "How to use 0.9.3's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.9.3 Recommendations
+
+Use this guide when you are adopting `0.9.3` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+
+## Recommended Default
+
+For most repos, the safest `0.9.3` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
+- when a wave-gate dimension has a documented gap that is not an actionable blocker, use `gap` instead of `pass` or `blocked` — the runtime treats it as a conditional pass
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.9.2` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+Use `gap` in wave-gate markers when a dimension has a documented gap that is not actionable in the current wave. For example, `live=gap` is appropriate when an infrastructure topology constraint prevents full live validation but the constraint is known, documented, and does not represent a regression. Do not use `gap` to hide actual failures or unreviewed work.
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.9.3` code path is:
+
+- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
+- inspect the queued rerun or resume request before manually relaunching the whole wave
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.

package/docs/guides/recommendations-0.9.4.md

@@ -0,0 +1,191 @@
+---
+title: "0.9.4 Recommendations"
+summary: "How to use 0.9.4's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+---
+
+# 0.9.4 Recommendations
+
+Use this guide when you are adopting `0.9.4` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+
+## Recommended Default
+
+For most repos, the safest `0.9.4` default is:
+
+- bound work with `budget.minutes`
+- leave generic `budget.turns` as advisory metadata
+- author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
+- use `resolve-policy` when the answer already exists in repo policy or shipped docs
+- prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
+- when a wave-gate dimension has a documented gap that is not an actionable blocker, use `gap` instead of `pass` or `blocked` — the runtime treats it as a conditional pass
+
+That recommendation matches the runtime:
+
+- executor launch metadata only emits hard turn-limit flags from `claude.maxTurns` or `opencode.steps`
+- open `stale` and `advisory` coordination records stay visible without reopening the active blocking edge
+- recoverable launcher failures queue targeted retry state instead of immediately escalating to broad terminal wave failure
+
+## 1. Budgets
+
+Treat the two budget knobs differently:
+
+- `budget.minutes` is the primary attempt budget
+- generic `budget.turns` is only a planning hint
+- `claude.maxTurns` or `opencode.steps` are the hard runtime ceilings when you actually want deterministic turn stopping
+
+Recommended pattern for synthesis-heavy implementation or closure work:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "implementation-default": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 35,
+          "turns": 12
+        }
+      }
+    }
+  }
+}
+```
+
+In that pattern, `35` minutes is real policy. `12` turns is only guidance for planning and preview metadata.
+
+Only set a hard runtime ceiling when you deliberately want the runtime itself to stop:
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "bounded-closure": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "minutes": 20
+        },
+        "claude": {
+          "maxTurns": 6
+        }
+      }
+    }
+  }
+}
+```
+
+## 2. Softer Coordination States
+
+`0.9.2` keeps “still visible” separate from “still blocking”.
+
+Use these states intentionally:
+
+| State | Use it for | What the runtime does |
+| --- | --- | --- |
+| `soft` | follow-up that still matters but should not be treated like proof failure | remains visible and may still drive repair or retry targeting |
+| `stale` | outdated clarification or blocker context kept for history | visible in control state, but does not reopen blocking by itself |
+| `advisory` | known issue, note, or human context that should stay visible without blocking closure | visible in control state, but does not own the active blocking edge |
+
+Practical command paths:
+
+```bash
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the rollout guide."
+```
+
+Use them when the repo already knows the answer, the remaining item is informational, or the follow-up should stay visible for the next wave without holding the current wave hostage.
+
+## 3. What Should Stay Hard
+
+Do not relax everything.
+
+Keep these hard or closure-critical unless you are intentionally changing wave policy:
+
+- missing proof or required deliverables
+- failed integration, documentation, or cont-QA closure gates
+- real human-feedback or escalation requirements that block safe continuation
+- requests or clarifications that still represent unresolved ownership or policy ambiguity for the current wave
+
+Use `gap` in wave-gate markers when a dimension has a documented gap that is not actionable in the current wave. For example, `live=gap` is appropriate when an infrastructure topology constraint prevents full live validation but the constraint is known, documented, and does not represent a regression. Do not use `gap` to hide actual failures or unreviewed work.
+
+If the current wave cannot truthfully close without the answer, keep it blocking.
+
+## 4. Recovery Recommendation
+
+My recommendation after reviewing the current `0.9.4` code path is:
+
+- let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
+- inspect the queued rerun or resume request before manually relaunching the whole wave
+- preserve reusable proof from successful sibling owners whenever the reducer already identified it as reusable
+
+That is the shape the launcher now prefers. It only broadens failure when the remaining blockers are still proof-critical or otherwise non-recoverable.
+
+## 5. Suggested Operator Policy
+
+For most repo-owned runbooks:
+
+- teach authors to use `budget.minutes` first
+- teach operators to downgrade only non-proof follow-up
+- treat `resolve-policy` as the preferred path when the answer already exists in docs or repo policy
+- escalate to a full-wave rerun only after targeted recovery proves insufficient
+
+If you want a single sentence policy:
+
+> Keep proof and closure strict, keep generic turns advisory, and keep non-proof context visible without letting it accidentally own wave closure.
+
+
+## Laddered Gate Modes (new in 0.9.4)
+
+Waves now have three gate strictness tiers based on wave number:
+
+| Mode | Default waves | What's required to advance |
+|------|--------------|---------------------------|
+| **bootstrap** | 0-3 | Implementation agents exit 0 + deliverables exist |
+| **standard** | 4-9 | + A0 verdict required, doc closure recommended |
+| **strict** | 10+ | Full ceremony: all signals, all stewards, all proof |
+
+### Configuration
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 4,
+      "strict": 10
+    },
+    "bootstrapPassConditions": {
+      "requireTestsPass": true,
+      "requireDeliverablesExist": true,
+      "requireExitCodeZero": true
+    },
+    "testCommand": "pnpm test:repo"
+  }
+}
+```
+
+### Steward threshold fix
+
+`requireDocumentationStewardFromWave` and `requireIntegrationStewardFromWave`
+are now strictly respected. Previously, the documentation steward was required
+whenever component promotions were active, regardless of the threshold setting.
+
+### Migration from 0.9.3
+
+No breaking changes. Existing repos get bootstrap mode for waves 0-3 by default.
+To keep the old strict behavior for all waves, set:
+
+```json
+{
+  "validation": {
+    "gateModeThresholds": {
+      "bootstrap": 0,
+      "standard": 0,
+      "strict": 0
+    }
+  }
+}
+```

package/docs/guides/sandboxed-environments.md

@@ -8,7 +8,7 @@ Typical examples:
 - Nemoshell or similar hosted terminal sandboxes
 - Docker or devcontainer setups where the client process is disposable but the workspace and state volume persist
 
-The core rule in `0.9.2` is simple:
+The core rule in `0.9.3` is simple:
 
 - clients should be short-lived
 - supervision should be long-lived
@@ -94,7 +94,7 @@ If the sandbox only gives you short exec windows, `wave autonomous` should not b
 
 ## Docker And Containerized Setups
 
-Docker works well with the `0.9.2` process-backed runner model, but only if the state directories survive container restarts.
+Docker works well with the `0.9.3` process-backed runner model, but only if the state directories survive container restarts.
 
 Recommended container posture:
 

package/docs/plans/current-state.md

@@ -1,10 +1,10 @@
 # Current State
 
-- The published package is `0.9.2`; that release keeps the shipped monorepo, design-role, and signal-hygiene surfaces, but now also moves live agent execution to detached process runners, reduces tmux and memory pressure during wide orchestration bursts, hardens the sandbox-safe supervisor path for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar short-lived exec environments, and documents the current authenticated Wave Control plus Corridor-backed security surface that already ships in this repo.
+- The published package is `0.9.4`; that release keeps the shipped monorepo, design-role, signal-hygiene, detached process-runner, and sandbox supervisor surfaces, and now also accepts `gap` as a valid wave-gate dimension value (alongside `pass`, `concerns`, and `blocked`) so that agents reporting a documented gap no longer trigger missing-wave-gate failures. First-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, and the interactive setup flow shows descriptive help text and inline option explanations. The current authenticated Wave Control plus Corridor-backed security surface continues to ship in this repo.
 - The canonical shipped runtime architecture is documented in `docs/plans/end-state-architecture.md`; the sandbox-runtime companion is `docs/plans/sandbox-end-state-architecture.md`; historical cutover notes remain in `docs/plans/architecture-hardening-migration.md`.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
-- The recommended `0.9.2` operating stance is documented in `docs/guides/recommendations-0.9.2.md`: keep proof and closure strict, keep generic `budget.turns` advisory, and use softer coordination states only for non-proof follow-up.
+- The recommended `0.9.4` operating stance is documented in `docs/guides/recommendations-0.9.4.md`: keep proof and closure strict, keep generic `budget.turns` advisory, and use softer coordination states only for non-proof follow-up.
 - Sandbox-safe setup guidance now ships in `docs/guides/sandboxed-environments.md`: use `wave submit/supervise/status/wait/attach` for short-lived clients, keep `tmux` optional and dashboard-only, and preserve `.tmp/` plus `.wave/` when running inside Nemoshell or Docker.
 - Runtime launch entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and point operators at `pnpm exec wave self-update` when a newer published package exists.
 - The companion control plane now ships in two packages:

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.9.2` surface.
+This page is the practical repo-upgrade guide for the current `0.9.4` surface.
 
 Use it when you are:
 
@@ -12,6 +12,36 @@ For the completed internal architecture cutover record, see [architecture-harden
 
 For the sandbox-specific long-running execution target, including async `submit/status/wait` semantics and daemon ownership goals, see [sandbox-end-state-architecture.md](./sandbox-end-state-architecture.md).
 
+
+## What `0.9.4` Changes
+
+The `0.9.4` surface adds laddered gate modes and fixes the steward threshold enforcement.
+
+- **Laddered gate modes**: bootstrap (waves 0-3), standard (4-9), strict (10+). Bootstrap mode requires only implementation agent exit 0 and deliverables exist — no formal QA signals needed.
+- **Steward threshold fix**: `requireDocumentationStewardFromWave` is now strictly respected. Previously it was OR'd with `componentPromotionRuleActive`.
+- **New config fields**: `gateModeThresholds`, `bootstrapPassConditions`, `testCommand`, `testCommandTimeout`.
+- **No breaking changes**: existing repos get bootstrap mode for waves 0-3 by default.
+
+## What `0.9.4` Changes
+
+The current `0.9.4` surface keeps everything from `0.9.2` and adds two focused improvements with no breaking changes.
+
+The practical changes are:
+
+- `WAVE_GATE_REGEX` now accepts `gap` alongside `pass|concerns|blocked` for all five gate dimensions (architecture, integration, durability, live, docs), so agents that report a documented gap no longer have their marker rejected entirely
+- `validateContQaSummary` treats `gap` dimension values as a conditional pass (`ok: true`, `statusCode: conditional-pass`) instead of a hard blocker
+- the cont-QA coordination prompt now documents `gap` as a valid dimension value
+- first-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, matching existing `wave draft` behavior
+- `wave project setup` now shows descriptive help text before each prompt, explains all template and posture options inline, and adds whitespace between question groups for readability
+- `PromptSession` gains a `describe(text)` method for writing contextual help to stderr during interactive setup flows
+- `parseArgs` now passes the loaded config object through to `runLauncherCli`, avoiding a redundant `loadWaveConfig()` call
+
+There are no breaking changes. Just upgrade with `pnpm up @chllming/wave-orchestration` and run `pnpm exec wave upgrade`.
+
+If your repo uses wave-gate markers, you can now use `gap` for dimensions where the gap is documented and not an actionable blocker.
+
+For the practical `0.9.4` operating stance after the upgrade, read [../guides/recommendations-0.9.4.md](../guides/recommendations-0.9.4.md).
+
 ## What `0.9.2` Changes
 
 The current `0.9.2` surface keeps the packaged operator-guidance alignment, monorepo project support, and project-aware default telemetry from `0.9.0`, but adds a more sandbox-friendly execution model and lower-overhead live orchestration.
@@ -150,10 +180,11 @@ pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
 
 Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` when you need to reattach to a tmux-backed dashboard after the upgrade.
 
-## `0.9.2` Release Model
+## `0.9.4` Release Model
 
-The current `0.9.2` surface combines these strands:
+The current `0.9.4` surface combines these strands:
 
+- the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.4`
 - the detached process-runner and sandbox supervisor hardening released in `0.9.2`
 - the shipped `0.9.0` monorepo project support and project-aware runtime isolation
 - the shipped `design` worker role and hybrid design-steward flow introduced in `0.8.5`
@@ -261,7 +292,7 @@ The interactive `wave draft` flow supports `design` as a worker role and scaffol
 
 ## Version-Specific Upgrade Guidance
 
-## Upgrading From `0.8.5` To `0.8.6`
+## Upgrading From `0.8.5` To `0.9.4`
 
 This is the smallest upgrade, but it changes the live wait-loop contract for external automation and intentionally long-running agents.
 
@@ -298,7 +329,7 @@ If the repo copied starter surface, sync:
 - if the repo uses long-running watchers, confirm they can write the ack file where the prompt tells them to
 - reroute one targeted feedback or coordination request and confirm the resident signal version changes even when the signal kind stays the same
 
-## Upgrading From `0.8.4` To `0.8.6`
+## Upgrading From `0.8.4` To `0.9.4`
 
 ### What changed
 
@@ -336,54 +367,7 @@ If your repo copied starter config defaults, also sync the `designRolePromptPath
 - hybrid design stewards rejoin implementation when they explicitly own code
 - long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
 
-## Upgrading From `0.8.3` To `0.8.6`
-
-This is the most common one-step package upgrade path.
-
-### What changed across that range
-
-- `0.8.4` tightened contradiction replay, component-promotion threshold handling, and projection persistence boundaries
-- `0.8.5` ships the `design` worker role, the `role-design` and `tui-design` starter bundles, and the hybrid design-steward runtime model as part of the published package
-- `0.8.6` adds versioned signal snapshots, `signal-hygiene`, prompt-injected signal ack loops, and the seeded operator wrappers
-- current operator and planner docs now describe the shipped surface directly instead of splitting behavior between a published package and newer `main`-only additions
-
-### Required repo changes
-
-Usually none if the repo does not copy starter prompts, skills, planning docs, or wrapper scripts.
-
-### Strongly recommended sync
-
-If the repo copied starter surface, sync:
-
-- `docs/agents/wave-design-role.md`
-- `skills/role-design/`
-- `skills/tui-design/`
-- `skills/signal-hygiene/`
-- `scripts/wave-status.sh`
-- `scripts/wave-watch.sh`
-- `docs/guides/author-and-run-waves.md`
-- `docs/guides/signal-wrappers.md`
-- `docs/guides/planner.md`
-- `docs/reference/skills.md`
-- `docs/reference/sample-waves.md`
-- `docs/plans/current-state.md`
-- `docs/plans/wave-orchestrator.md`
-- `docs/plans/end-state-architecture.md`
-
-If the repo copied starter `wave.config.json` defaults, also sync:
-
-- `roles.designRolePromptPath`
-- `skills.byRole.design`
-- `executors.profiles.design-pass`
-
-### Validation focus
-
-- confirm contradiction-blocked replay cases still compare cleanly if the repo keeps replay fixtures
-- if the repo uses design stewards, confirm packet-only design waves still block implementation until `ready-for-implementation`
-- if the repo uses hybrid design stewards, confirm the same agent rejoins implementation only when the authored wave explicitly gives it code ownership
-- if the repo uses long-running agents or shell automation, confirm the new wrapper exit contract and ack-loop semantics before relying on an older polling script
-
-## Upgrading From `0.8.3` To `0.9.2`
+## Upgrading From `0.8.3` To `0.9.4`
 
 Treat this as one move to the current `0.9.2` surface.
 
@@ -418,7 +402,7 @@ If your repo copied starter docs or skills, sync:
 - dry-run one design-steward wave if the repo wants the new authored surface
 - if the repo uses long-running watcher agents or shell automation, validate `scripts/wave-status.sh` and `scripts/wave-watch.sh` against a live or staged lane
 
-## Upgrading From `0.6.x` Or `0.7.x` To `0.9.2`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.9.4`
 
 This is the main migration path for older adopted repos.
 
@@ -459,7 +443,7 @@ pnpm exec wave control proof get --lane main --wave 0 --json
 
 If the repo carries proof-first waves, verify that required proof artifacts still exist locally and not only in historical summaries.
 
-## Upgrading From `0.5.x` Or Earlier To `0.9.2`
+## Upgrading From `0.5.x` Or Earlier To `0.9.4`
 
 Do not treat this as a tiny patch bump.
 
@@ -569,4 +553,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.9.2` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.
+The current `0.9.4` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, keeps the `0.8.7` policy and routing hardening, and now also packages the practical operator recommendations guide inside the release line. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/docs/reference/coordination-and-closure.md

@@ -428,9 +428,9 @@ The important distinction is:
 `cont-QA` must emit:
 
 - a final verdict
-- a final `[wave-gate]` marker
+- a final `[wave-gate]` marker with each of the five gate dimensions (architecture, integration, durability, live, docs) set to `pass`, `concerns`, `blocked`, or `gap`
 
-Final PASS requires all gate dimensions to pass in the final state.
+Final PASS requires all gate dimensions to be `pass` or `gap` in the final state. A `gap` value means the dimension has a documented gap that is not an actionable blocker; it is treated as a conditional pass (`ok: true`, `statusCode: conditional-pass`) with detail text listing which dimensions have documented gaps.
 
 ## Why The Closure Model Works
 

package/docs/reference/runtime-config/README.md

@@ -191,7 +191,7 @@ Practical guidance:
 - prefer `budget.minutes` for normal synthesis, integration, and closure work
 - use generic `budget.turns` as a planning hint, not a hard failure trigger
 - only set `claude.maxTurns` or `opencode.steps` when you deliberately want a hard ceiling for that runtime
-- see [../../guides/recommendations-0.9.2.md](../../guides/recommendations-0.9.2.md) for the recommended `0.9.2` operating stance that combines advisory turn budgets with softer non-proof coordination states
+- see [../../guides/recommendations-0.9.3.md](../../guides/recommendations-0.9.3.md) for the recommended `0.9.3` operating stance that combines advisory turn budgets with softer non-proof coordination states
 
 ## Runtime Pages
 
@@ -203,7 +203,7 @@ Practical guidance:
 
 `wave.config.json` may also declare a `waveControl` block for local-first telemetry delivery.
 
-Packaged defaults in `@chllming/wave-orchestration@0.9.2`:
+Packaged defaults in `@chllming/wave-orchestration@0.9.3`:
 
 - `endpoint`: `https://wave-control.up.railway.app/api/v1`
 - `reportMode`: `metadata-only`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,28 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.9.4",
+      "date": "2026-03-30",
+      "summary": "Gap-value wave-gate fix and first-time project setup UX improvements.",
+      "features": [
+        "WAVE_GATE_REGEX now accepts `gap` alongside `pass|concerns|blocked` for all five gate dimensions (architecture, integration, durability, live, docs), so agents reporting a documented gap no longer have their marker rejected entirely.",
+        "`validateContQaSummary` now treats `gap` dimension values as a conditional pass (`ok: true`, `statusCode: conditional-pass`) instead of a hard blocker, with detail text listing which dimensions have documented gaps.",
+        "The cont-QA coordination prompt now documents `gap` as a valid dimension value alongside `pass|concerns|blocked`.",
+        "First-time `wave launch` now auto-triggers `wave project setup` when no project profile exists, matching existing `wave draft` behavior. (Contributed by @justanothernate in #54)",
+        "`wave project setup` now shows descriptive help text before each prompt, explains all template and posture options inline, and adds whitespace between question groups for readability. (Contributed by @justanothernate in #54)",
+        "`PromptSession` gains a `describe(text)` method for writing contextual help to stderr during interactive setup flows.",
+        "`parseArgs` now passes the loaded config object through to `runLauncherCli`, avoiding a redundant `loadWaveConfig()` call.",
+        "Release docs, migration guidance, runtime-config and closure references, the manifest, and the tracked install-state fixtures now all point at the `0.9.4` surface.",
+        "Planner migration guidance and the `planner-agentic` bundle placeholder remain part of the shipped current-surface docs so adopted repos still have one aligned upgrade target."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.9.4` release surface.",
+        "Push the `v0.9.4` tag after the release commit so the GitHub publish workflow can publish the matching npm package version.",
+        "If your repo copied starter docs or runbooks, sync `README.md`, `docs/README.md`, `docs/plans/current-state.md`, `docs/plans/migration.md`, `docs/reference/coordination-and-closure.md`, `docs/reference/runtime-config/README.md`, and `docs/guides/recommendations-0.9.4.md` so local guidance matches the packaged release."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.9.2",
       "date": "2026-03-29",

package/scripts/wave-orchestrator/agent-state.mjs

@@ -50,7 +50,7 @@ const WAVE_SECURITY_REGEX =
 const WAVE_DESIGN_REGEX =
   /^\[wave-design\]\s*state=(ready-for-implementation|needs-clarification|blocked)\s+decisions=(\d+)\s+assumptions=(\d+)\s+open_questions=(\d+)\s*(?:detail=(.*))?$/gim;
 const WAVE_GATE_REGEX =
-  /^\[wave-gate\]\s*architecture=(pass|concerns|blocked)\s+integration=(pass|concerns|blocked)\s+durability=(pass|concerns|blocked)\s+live=(pass|concerns|blocked)\s+docs=(pass|concerns|blocked)\s*(?:detail=(.*))?$/gim;
+  /^\[wave-gate\]\s*architecture=(pass|concerns|blocked|gap)\s+integration=(pass|concerns|blocked|gap)\s+durability=(pass|concerns|blocked|gap)\s+live=(pass|concerns|blocked|gap)\s+docs=(pass|concerns|blocked|gap)\s*(?:detail=(.*))?$/gim;
 const WAVE_GAP_REGEX =
   /^\[wave-gap\]\s*kind=(architecture|integration|durability|ops|docs)\s*(?:detail=(.*))?$/gim;
 const WAVE_COMPONENT_REGEX =
@@ -1268,17 +1268,34 @@ export function validateContQaSummary(agent, summary, options = {}) {
       detail: summary.verdict.detail || "Verdict read from cont-QA report.",
     };
   }
+  const hardBlockers = [];
+  const documentedGaps = [];
   for (const key of ["architecture", "integration", "durability", "live", "docs"]) {
-    if (summary.gate[key] !== "pass") {
-      return {
-        ok: false,
-        statusCode: `gate-${key}-${summary.gate[key]}`,
-        detail:
-          summary.gate.detail ||
-          `Final cont-QA gate did not pass ${key}; got ${summary.gate[key]}.`,
-      };
+    if (summary.gate[key] === "gap") {
+      documentedGaps.push(key);
+    } else if (summary.gate[key] !== "pass") {
+      hardBlockers.push(key);
     }
   }
+  if (hardBlockers.length > 0) {
+    const key = hardBlockers[0];
+    return {
+      ok: false,
+      statusCode: `gate-${key}-${summary.gate[key]}`,
+      detail:
+        summary.gate.detail ||
+        `Final cont-QA gate did not pass ${key}; got ${summary.gate[key]}.`,
+    };
+  }
+  if (documentedGaps.length > 0) {
+    return {
+      ok: true,
+      statusCode: "conditional-pass",
+      detail:
+        summary.gate.detail ||
+        `cont-QA gate passed with documented gaps in: ${documentedGaps.join(", ")}.`,
+    };
+  }
   return {
     ok: true,
     statusCode: "pass",

package/scripts/wave-orchestrator/config.mjs

@@ -531,6 +531,20 @@ function normalizeValidation(rawValidation = {}) {
       rawValidation.requireAgentComponentsFromWave,
       0,
     ),
+    gateModeThresholds: {
+      bootstrap: rawValidation.gateModeThresholds?.bootstrap ?? 0,
+      standard: rawValidation.gateModeThresholds?.standard ?? 4,
+      strict: rawValidation.gateModeThresholds?.strict ?? 10,
+    },
+    bootstrapPassConditions: {
+      requireA0Verdict: rawValidation.bootstrapPassConditions?.requireA0Verdict ?? false,
+      requireProofSignals: rawValidation.bootstrapPassConditions?.requireProofSignals ?? false,
+      requireTestsPass: rawValidation.bootstrapPassConditions?.requireTestsPass ?? true,
+      requireDeliverablesExist: rawValidation.bootstrapPassConditions?.requireDeliverablesExist ?? true,
+      requireExitCodeZero: rawValidation.bootstrapPassConditions?.requireExitCodeZero ?? true,
+    },
+    testCommand: typeof rawValidation.testCommand === "string" ? rawValidation.testCommand : null,
+    testCommandTimeout: typeof rawValidation.testCommandTimeout === "number" ? rawValidation.testCommandTimeout : 120,
   };
 }
 

package/scripts/wave-orchestrator/coordination.mjs

@@ -253,7 +253,7 @@ export function buildExecutionPrompt({
       ? [
           `- Because you are Agent ${contQaAgentId}, your cont-QA report must end with exactly one standalone line in the form \`Verdict: PASS\`, \`Verdict: CONCERNS\`, or \`Verdict: BLOCKED\`.`,
           "- Also emit one matching structured marker in your terminal output: `[wave-verdict] pass`, `[wave-verdict] concerns`, or `[wave-verdict] blocked`.",
-          "- Emit one final structured gate marker: `[wave-gate] architecture=<pass|concerns|blocked> integration=<pass|concerns|blocked> durability=<pass|concerns|blocked> live=<pass|concerns|blocked> docs=<pass|concerns|blocked> detail=<short-note>`.",
+          "- Emit one final structured gate marker: `[wave-gate] architecture=<pass|concerns|blocked|gap> integration=<pass|concerns|blocked|gap> durability=<pass|concerns|blocked|gap> live=<pass|concerns|blocked|gap> docs=<pass|concerns|blocked|gap> detail=<short-note>`.",
           "- Only use `Verdict: PASS` when the wave is coherent enough to unblock the next wave.",
           `- Do not declare PASS until the documentation gate is closed: impacted implementation-owned docs must exist, ${sharedPlanDocList} must reflect plan-affecting outcomes, and no unresolved architecture-versus-plans drift remains.`,
           "- If shared-plan reconciliation is still active inside the wave, require the exact remaining doc delta and an explicit `closed` or `no-change` note from the documentation steward or named owner before finalizing. Do not treat ownership handoff alone as the blocker.",

package/scripts/wave-orchestrator/gate-engine.mjs

@@ -138,6 +138,46 @@ function validateEnvelopeForRun(runInfo, envelope, options = {}) {
   };
 }
 
+
+// --- Laddered gate modes (0.9.4) ---
+export function resolveGateMode(waveNumber, thresholds) {
+  if (!thresholds) return "strict";
+  if (waveNumber < (thresholds.standard ?? 4)) return "bootstrap";
+  if (waveNumber < (thresholds.strict ?? 10)) return "standard";
+  return "strict";
+}
+
+export function evaluateBootstrapGate(wave, agentRuns, options = {}) {
+  const conditions = options.bootstrapPassConditions ?? {};
+  const summaries = options.summaries ?? new Map();
+  
+  // Check implementation agents (non-A0, non-A8, non-A9)
+  const implAgents = agentRuns.filter(a => 
+    !["A0", "E0", "A8", "A9"].includes(a.agentId)
+  );
+  
+  for (const agent of implAgents) {
+    const summary = summaries.get(agent.agentId);
+    if (!summary) continue;
+    
+    // Must have exit code 0
+    if (conditions.requireExitCodeZero !== false && summary.exitCode !== 0) {
+      return { ok: false, statusCode: "blocked", detail: `${agent.agentId} exit code ${summary.exitCode}` };
+    }
+    
+    // Check deliverables exist
+    if (conditions.requireDeliverablesExist !== false && summary.deliverables) {
+      const missing = summary.deliverables.filter(d => !d.exists);
+      if (missing.length > 0) {
+        return { ok: false, statusCode: "concerns", detail: `${agent.agentId} missing deliverables: ${missing.map(d=>d.path).join(", ")}` };
+      }
+    }
+  }
+  
+  return { ok: true, statusCode: "pass", detail: "bootstrap-pass: impl agents completed with deliverables" };
+}
+// --- End laddered gate modes ---
+
 export function materializeAgentExecutionSummaryForRun(wave, runInfo, options = {}) {
   const statusRecord = readStatusRecordIfPresent(runInfo.statusPath);
   if (!statusRecord) {

package/scripts/wave-orchestrator/install.mjs

@@ -69,7 +69,7 @@ export const STARTER_TEMPLATE_PATHS = [
   "docs/guides/author-and-run-waves.md",
   "docs/guides/monorepo-projects.md",
   "docs/guides/planner.md",
-  "docs/guides/recommendations-0.9.2.md",
+  "docs/guides/recommendations-0.9.4.md",
   "docs/guides/sandboxed-environments.md",
   "docs/guides/signal-wrappers.md",
   "docs/guides/terminal-surfaces.md",

package/scripts/wave-orchestrator/launcher.mjs

@@ -332,7 +332,7 @@ function parseArgs(argv) {
       continue;
     }
     if (arg === "--help" || arg === "-h") {
-      return { help: true, lanePaths, options };
+      return { help: true, lanePaths, options, config };
     }
     if (arg === "--dry-run") {
       options.dryRun = true;
@@ -474,7 +474,7 @@ function parseArgs(argv) {
   if (!options.dryRun && options.terminalSurface === "none") {
     throw new Error("--terminal-surface none is only supported with --dry-run");
   }
-  return { help: false, lanePaths, options };
+  return { help: false, lanePaths, options, config };
 }
 
 // --- Local wrappers that bind engine calls to launcher scope ---
@@ -755,7 +755,25 @@ export async function runLauncherCli(argv) {
     printUsage(parsed.lanePaths, parsed.options.terminalSurface);
     return;
   }
-  const { lanePaths, options } = parsed;
+  const { lanePaths, options, config } = parsed;
+
+  // Auto-run project setup on first launch if no profile exists yet.
+  const projectId = options.project || config.defaultProject;
+  if (!readProjectProfile({ config, project: projectId })) {
+    const { stderr: stderrStream } = await import("node:process");
+    stderrStream.write(
+      "\n  No project profile found — running first-time setup.\n" +
+        "  You can re-run this later with: wave project setup\n\n",
+    );
+    const { runPlannerCli } = await import("./planner.mjs");
+    await runPlannerCli(["project", "setup", ...(projectId ? ["--project", projectId] : [])]);
+    // Re-read the terminal surface from the newly created profile.
+    const freshProfile = readProjectProfile({ config, project: projectId });
+    if (freshProfile) {
+      options.terminalSurface = resolveDefaultTerminalSurface(freshProfile);
+    }
+  }
+
   const supervisorRunId = String(process.env.WAVE_SUPERVISOR_RUN_ID || "").trim() || null;
   const launcherProgressPath = launcherProgressPathForRun(lanePaths, supervisorRunId);
   const writeLauncherRunProgress = (patch = {}) => {

package/scripts/wave-orchestrator/planner.mjs

@@ -486,6 +486,10 @@ class PromptSession {
     }
   }
 
+  describe(text) {
+    stderr.write(`  ${text}\n`);
+  }
+
   async close() {
     this.interface?.close();
   }
@@ -2925,7 +2929,13 @@ async function runProjectSetupFlow(options = {}) {
     const laneChoices = Array.from(
       new Set([config.defaultLane, ...projectLanes, ...Object.keys(config.lanes || {})].filter(Boolean)),
     );
+    stderr.write("\n  Wave project setup — answer a few questions so Wave can tailor defaults for this repo.\n  Press Enter to accept the default shown in [brackets].\n\n");
+    prompt.describe("Is this a fresh start, or has Wave been used in this repo before?");
     const newProject = await prompt.askBoolean("Treat this repository as a new project?", base.newProject);
+
+    prompt.describe("\nShould you review agent progress yourself, or let them run autonomously?");
+    prompt.describe("  oversight    — you review progress and approve risky steps (recommended)");
+    prompt.describe("  dark-factory — agents run end-to-end without human checkpoints");
     const defaultOversightMode = normalizeOversightMode(
       await prompt.askChoice(
         "Default execution posture",
@@ -2933,6 +2943,10 @@ async function runProjectSetupFlow(options = {}) {
         base.defaultOversightMode,
       ),
     );
+
+    prompt.describe("\nHow do you want to watch agent sessions?");
+    prompt.describe("  vscode — agent sessions appear as VS Code terminal tabs");
+    prompt.describe("  tmux   — agent sessions run in tmux panes (terminal-native)");
     const defaultTerminalSurface = normalizeTerminalSurface(
       await prompt.askChoice(
         "Default terminal surface",
@@ -2940,6 +2954,12 @@ async function runProjectSetupFlow(options = {}) {
         base.defaultTerminalSurface,
       ),
     );
+
+    prompt.describe("\nWhat kind of work will waves usually do?");
+    prompt.describe("  implementation — building features, fixing bugs, writing code (most common)");
+    prompt.describe("  qa             — test coverage, test infrastructure, validation work");
+    prompt.describe("  infra          — deployment, CI/CD, infrastructure changes");
+    prompt.describe("  release        — versioning, changelog, release coordination");
     const template = normalizeDraftTemplate(
       await prompt.askChoice(
         "Default draft template",
@@ -2947,11 +2967,20 @@ async function runProjectSetupFlow(options = {}) {
         base.plannerDefaults.template,
       ),
     );
+
+    prompt.describe("\nWhich lane should new waves go into? A lane is just an ordered sequence of waves.");
+    prompt.describe("'main' is the default and usually fine to start with.");
     const lane = await prompt.askChoice(
       "Default draft lane",
       laneChoices,
       base.plannerDefaults.lane,
     );
+
+    prompt.describe("\nDo you have deploy environments (e.g. staging, production) you want Wave to know about?");
+    prompt.describe("This helps Wave attach the right deployment skills when agents do infra or release work.");
+    prompt.describe("Supported providers: railway, docker-compose, kubernetes, ssh-manual.");
+    prompt.describe("Use 'custom' for anything else (GitHub Actions, Vercel, Cloudflare, etc.).");
+    prompt.describe("You can skip this now (enter 0) and add them later with 'wave project setup'.");
     const deployEnvironmentCount = await prompt.askInteger(
       "How many deploy environments should the planner remember?",
       base.deployEnvironments.length,

package/scripts/wave-orchestrator/wave-files.mjs

@@ -1786,8 +1786,7 @@ export function validateWaveDefinition(wave, options = {}) {
     }
   }
   const documentationRuleActive =
-    (documentationThreshold !== null && wave.wave >= documentationThreshold) ||
-    componentPromotionRuleActive;
+    documentationThreshold !== null && wave.wave >= documentationThreshold;
   if (documentationRuleActive) {
     const documentationStewards = wave.agents.filter((agent) =>
       agent.rolePromptPaths?.includes(laneProfile.roles.documentationRolePromptPath),

package/wave.config.json

@@ -31,51 +31,69 @@
     "profiles": {
       "implement-fast": {
         "id": "codex",
-        "tags": ["implementation"],
+        "tags": [
+          "implementation"
+        ],
         "budget": {
-          "turns": 12,
           "minutes": 45
         }
       },
       "deep-review": {
         "id": "claude",
-        "tags": ["integration", "review"],
+        "tags": [
+          "integration",
+          "review"
+        ],
         "budget": {
-          "turns": 10,
           "minutes": 30
         }
       },
       "eval-tuning": {
         "id": "codex",
-        "tags": ["eval", "tuning"],
+        "tags": [
+          "eval",
+          "tuning"
+        ],
         "budget": {
-          "turns": 14,
           "minutes": 45
         }
       },
       "docs-pass": {
         "id": "claude",
-        "tags": ["documentation"],
+        "tags": [
+          "documentation"
+        ],
         "budget": {
-          "turns": 8,
           "minutes": 20
         }
       },
       "design-pass": {
         "id": "claude",
-        "tags": ["design", "review"],
+        "tags": [
+          "design",
+          "review"
+        ],
         "budget": {
-          "turns": 10,
           "minutes": 30
         },
         "claude": {
-          "allowedTools": ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
+          "allowedTools": [
+            "Read",
+            "Edit",
+            "Write",
+            "Bash",
+            "Grep",
+            "Glob"
+          ]
         }
       },
       "planning-readonly": {
         "id": "codex",
         "model": "gpt-5-codex",
-        "tags": ["planning", "review"],
+        "tags": [
+          "planning",
+          "review"
+        ],
         "budget": {
           "minutes": 30
         },
@@ -83,25 +101,38 @@
           "search": true,
           "json": true,
           "sandbox": "read-only",
-          "config": ["model_reasoning_effort=high"]
+          "config": [
+            "model_reasoning_effort=high"
+          ]
         }
       },
       "security-review": {
         "id": "claude",
-        "tags": ["security", "review"],
+        "tags": [
+          "security",
+          "review"
+        ],
         "budget": {
-          "turns": 8,
           "minutes": 20
         },
         "claude": {
-          "allowedTools": ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
+          "allowedTools": [
+            "Read",
+            "Edit",
+            "Write",
+            "Bash",
+            "Grep",
+            "Glob"
+          ]
         }
       },
       "ops-triage": {
         "id": "opencode",
-        "tags": ["ops", "research"],
+        "tags": [
+          "ops",
+          "research"
+        ],
         "budget": {
-          "turns": 8,
           "minutes": 20
         }
       }
@@ -122,34 +153,81 @@
   },
   "skills": {
     "dir": "skills",
-    "base": ["wave-core", "repo-coding-rules"],
+    "base": [
+      "wave-core",
+      "repo-coding-rules"
+    ],
     "byRole": {
-      "design": ["role-design"],
-      "implementation": ["role-implementation"],
-      "integration": ["role-integration"],
-      "documentation": ["role-documentation"],
-      "cont-qa": ["role-cont-qa"],
-      "cont-eval": ["role-cont-eval"],
-      "security": ["role-security"],
-      "infra": ["role-infra"],
-      "deploy": ["role-deploy"],
-      "research": ["role-research"]
+      "design": [
+        "role-design"
+      ],
+      "implementation": [
+        "role-implementation"
+      ],
+      "integration": [
+        "role-integration"
+      ],
+      "documentation": [
+        "role-documentation"
+      ],
+      "cont-qa": [
+        "role-cont-qa"
+      ],
+      "cont-eval": [
+        "role-cont-eval"
+      ],
+      "security": [
+        "role-security"
+      ],
+      "infra": [
+        "role-infra"
+      ],
+      "deploy": [
+        "role-deploy"
+      ],
+      "research": [
+        "role-research"
+      ]
     },
     "byRuntime": {
-      "codex": ["runtime-codex"],
-      "claude": ["runtime-claude"],
-      "opencode": ["runtime-opencode"],
-      "local": ["runtime-local"]
+      "codex": [
+        "runtime-codex"
+      ],
+      "claude": [
+        "runtime-claude"
+      ],
+      "opencode": [
+        "runtime-opencode"
+      ],
+      "local": [
+        "runtime-local"
+      ]
     },
     "byDeployKind": {
-      "railway-cli": ["provider-railway"],
-      "railway-mcp": ["provider-railway"],
-      "docker-compose": ["provider-docker-compose"],
-      "kubernetes": ["provider-kubernetes"],
-      "aws": ["provider-aws"],
-      "github-release": ["provider-github-release"],
-      "ssh-manual": ["provider-ssh-manual"],
-      "custom": ["provider-custom-deploy"]
+      "railway-cli": [
+        "provider-railway"
+      ],
+      "railway-mcp": [
+        "provider-railway"
+      ],
+      "docker-compose": [
+        "provider-docker-compose"
+      ],
+      "kubernetes": [
+        "provider-kubernetes"
+      ],
+      "aws": [
+        "provider-aws"
+      ],
+      "github-release": [
+        "provider-github-release"
+      ],
+      "ssh-manual": [
+        "provider-ssh-manual"
+      ],
+      "custom": [
+        "provider-custom-deploy"
+      ]
     }
   },
   "planner": {
@@ -223,8 +301,12 @@
           "infra": "opencode",
           "deploy": "opencode"
         },
-        "fallbackExecutorOrder": ["claude", "opencode", "codex"]
+        "fallbackExecutorOrder": [
+          "claude",
+          "opencode",
+          "codex"
+        ]
       }
     }
   }
-}
+}