@chllming/wave-orchestration 0.9.1 → 0.9.3

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.9.1` surface.
+This page is the practical repo-upgrade guide for the current `0.9.3` surface.
 
 Use it when you are:
 
@@ -12,22 +12,44 @@ 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.1` Changes
+## What `0.9.3` Changes
 
-The current `0.9.1` 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.
+The current `0.9.3` 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.3` operating stance after the upgrade, read [../guides/recommendations-0.9.3.md](../guides/recommendations-0.9.3.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.
 
 The practical changes are:
 
 - live agent execution now uses detached process runners instead of per-agent tmux execution sessions, which reduces tmux churn and lowers memory pressure during broader fan-out
 - `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` are now the preferred path for short-lived clients and sandbox automation
 - supervisor recovery now reconciles launcher status and progress more conservatively, preserves the correct remaining wave range during multi-wave reruns, and keeps read-side status/wait calls aligned even after daemon loss
+- the packaged docs now cover the actual shipped owned-deployment Wave Control surface: Stack-authenticated browser access, Wave-managed approval states and provider grants, PATs, service tokens, encrypted per-user credentials, runtime env leasing, and the separate `services/wave-control-web` frontend
+- Corridor is now documented as a first-class security input, including direct versus broker versus hybrid mode, implementation-owned path matching, generated artifact paths, and the closure-gate interaction with the human security reviewer
 - a dedicated setup guide now ships for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar constrained environments
 - the `0.9.0` monorepo and project-aware state layout remains part of the release surface, including `defaultProject`, `projects.<projectId>`, project-scoped state roots, and project-aware CLI routing
-- the current release surface and tracked install-state fixtures now all move together on `0.9.1`
+- the current release surface and tracked install-state fixtures now all move together on `0.9.2`
 
-If your repo copied starter docs, shell automation, runbooks, or `wave.config.json` defaults, these are the areas most likely to need a sync before the `0.9.1` package cut.
+If your repo copied starter docs, shell automation, runbooks, or `wave.config.json` defaults, these are the areas most likely to need a sync before the `0.9.2` package cut.
 
-For a practical `0.9.1` operating stance after the upgrade, read [../guides/recommendations-0.9.1.md](../guides/recommendations-0.9.1.md).
+For a practical `0.9.2` operating stance after the upgrade, read [../guides/recommendations-0.9.2.md](../guides/recommendations-0.9.2.md).
 For the concrete operator setup in Nemoshell, Docker, and other sandboxed shells, also read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md).
 
 ## What `0.8.6` Changes
@@ -95,7 +117,7 @@ pnpm exec wave upgrade
 
 ### 3. Sync repo-owned starter surface only if you copied it
 
-The most common sync set for `0.9.1` is:
+The most common sync set for `0.9.2` is:
 
 - `docs/agents/wave-launcher-role.md`
 - `docs/agents/wave-orchestrator-role.md`
@@ -116,8 +138,10 @@ The most common sync set for `0.9.1` is:
 - `docs/context7/planner-agent/`
 - `docs/reference/wave-planning-lessons.md`
 - `docs/reference/cli-reference.md`
+- `docs/reference/corridor.md`
 - `docs/reference/skills.md`
 - `docs/reference/sample-waves.md`
+- `docs/reference/wave-control.md`
 - `docs/plans/current-state.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/wave-orchestrator.md`
@@ -146,20 +170,23 @@ 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.1` Release Model
+## `0.9.3` Release Model
 
-The current `0.9.1` surface is five changes together:
+The current `0.9.3` surface combines these strands:
 
-- the detached process-runner and sandbox supervisor hardening released in `0.9.1`
+- the gap-value wave-gate fix and first-time setup UX improvements released in `0.9.3`
+- 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`
 - the signal-driven long-running-agent and wrapper model introduced in `0.8.6`
 - the policy-consistency, targeted-recovery, capability-specific routing, and stable per-wave session reuse hardening introduced in `0.8.7`
-- the packaged recommendations guide, sandbox setup guide, and install-state alignment follow-up released in `0.9.1`
+- the current owned-deployment Wave Control surface: Stack-authenticated app access, provider grants, PATs, service tokens, encrypted per-user credentials, and runtime credential leasing
+- the Corridor-backed security surface: direct or brokered provider fetches, normalized per-wave artifacts, and closure gating before integration
+- the packaged recommendations guide, sandbox setup guide, and release-surface alignment follow-up that make the current docs describe that combined surface consistently
 
 ### Sandbox-safe execution and lower-overhead live runs
 
-This is the main new behavior in `0.9.1`.
+This is the main new behavior in `0.9.2`.
 
 The runtime now:
 
@@ -168,7 +195,7 @@ The runtime now:
 - keeps `wave attach --agent` usable through log-follow attach even when no live interactive terminal session exists
 - uses `wave submit/supervise/status/wait/attach` as the preferred sandbox-safe surface for short-lived clients
 
-If your repo copied sandbox, CI, or container runbooks, this is the main sync set to apply from `0.9.1`:
+If your repo copied sandbox, CI, or container runbooks, this is the main sync set to apply from `0.9.2`:
 
 - `README.md`
 - `docs/README.md`
@@ -177,6 +204,24 @@ If your repo copied sandbox, CI, or container runbooks, this is the main sync se
 - `docs/reference/cli-reference.md`
 - `docs/plans/sandbox-end-state-architecture.md`
 
+### Authenticated Wave Control and Corridor-backed security
+
+The same `0.9.2` doc surface also now describes the current control-plane and security model as shipped:
+
+- owned Wave Control deployments use Stack for browser sign-in, then apply Wave-managed approval states and provider grants on top of that identity
+- approved users and superusers can issue PATs for scoped repo-runtime access, while dedicated service tokens keep machine-admin workflows separate from user-owned runtime credentials
+- arbitrary stored credentials are encrypted at rest and only returned through explicit runtime lease responses
+- `externalProviders.corridor` can run direct, brokered through an owned Wave Control deployment, or hybrid; the result is persisted as a normalized security artifact and can block closure before integration
+
+If your repo copied release docs, security runbooks, or Wave Control setup docs, this is the main sync set to apply from `0.9.2`:
+
+- `README.md`
+- `docs/README.md`
+- `docs/reference/runtime-config/README.md`
+- `docs/reference/coordination-and-closure.md`
+- `docs/reference/corridor.md`
+- `docs/reference/wave-control.md`
+
 ### Signal-driven waiting and wrapper model
 
 This is the main new behavior in `0.8.6`.
@@ -237,7 +282,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.3`
 
 This is the smallest upgrade, but it changes the live wait-loop contract for external automation and intentionally long-running agents.
 
@@ -274,7 +319,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.3`
 
 ### What changed
 
@@ -312,56 +357,9 @@ 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.1`
+## Upgrading From `0.8.3` To `0.9.3`
 
-Treat this as one move to the current `0.9.1` surface.
+Treat this as one move to the current `0.9.2` surface.
 
 ### What changed across that range
 
@@ -394,7 +392,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.1`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.9.3`
 
 This is the main migration path for older adopted repos.
 
@@ -435,7 +433,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.1`
+## Upgrading From `0.5.x` Or Earlier To `0.9.3`
 
 Do not treat this as a tiny patch bump.
 
@@ -545,4 +543,4 @@ For repos that depend on replay parity, replay at least:
 
 ## Summary
 
-The current `0.9.1` 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.3` 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/cli-reference.md

@@ -629,7 +629,7 @@ Interactive draft currently offers worker role kinds:
 - `research`
 - `security`
 
-Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.1` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.2` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
 
 ## Ad-Hoc Task Commands
 

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

@@ -36,6 +36,8 @@ At runtime, those distinctions map onto separate modules:
 
 Closure roles are resolved from the wave definition first, then from starter defaults. In other words, integration, documentation, `cont-QA`, `cont-EVAL`, and security review keep the same semantics even when a wave overrides the default role ids such as `A8`, `A9`, `A0`, `E0`, or `A7`.
 
+If `externalProviders.corridor.enabled` is on, Wave also materializes a normalized Corridor artifact before security and integration run. Security review still owns the human-readable report and `[wave-security]` marker, but the security gate can fail closed when the saved Corridor artifact reports a fetch failure or matched blocking findings on implementation-owned paths.
+
 ## Durable State Surfaces
 
 The runtime writes several different artifacts, but they do different jobs:
@@ -56,6 +58,12 @@ The runtime writes several different artifacts, but they do different jobs:
   `.tmp/<lane>-wave-launcher/inboxes/wave-<n>/<agent>.md`
 - integration summary:
   `.tmp/<lane>-wave-launcher/integration/wave-<n>.json`
+- security summary:
+  `.tmp/<lane>-wave-launcher/security/wave-<n>.json`
+- security markdown summary:
+  `.tmp/<lane>-wave-launcher/security/wave-<n>.md`
+- Corridor security context:
+  `.tmp/<lane>-wave-launcher/security/wave-<n>-corridor.json`
 - wave dashboard:
   `.tmp/<lane>-wave-launcher/dashboards/wave-<n>.json`
 - run-state:
@@ -134,7 +142,7 @@ Practical rule:
 
 That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
 
-For the practical `0.9.1` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.1.md](../guides/recommendations-0.9.1.md).
+For the practical `0.9.2` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.2.md](../guides/recommendations-0.9.2.md).
 
 This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
 
@@ -392,6 +400,15 @@ If present, security review must emit a final `[wave-security]` marker and publi
 - `concerns` remains visible in summaries and traces
 - `clear` is only valid when no unresolved findings or approvals remain
 
+Corridor does not replace that review. When `externalProviders.corridor.enabled` is on:
+
+- Wave first materializes the normalized Corridor artifact
+- `requiredAtClosure: true` turns provider fetch failures into `corridor-fetch-failed`
+- matched findings at or above the configured threshold turn the gate into `corridor-blocked`
+- matched findings still stay visible in security and integration summaries even when the human reviewer reports only advisory concerns
+
+Only implementation-owned non-doc, non-`.tmp/`, non-markdown paths are eligible for Corridor matching. See [corridor.md](./corridor.md) for the provider-specific rules.
+
 ### Integration
 
 Integration must reconcile cross-agent state and report `ready-for-doc-closure` only when there is no remaining meaningful contradiction, blocker, proof gap, or deploy risk.
@@ -411,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/corridor.md

@@ -0,0 +1,225 @@
+---
+title: "Corridor"
+summary: "How Wave loads Corridor security context, matches findings against implementation-owned paths, and uses the result during closure."
+---
+
+# Corridor
+
+Corridor is Wave's optional external security-context provider.
+
+It does not replace the report-owning security reviewer. Instead, it adds a machine-readable guardrail and findings input that Wave can materialize before security and integration closure run.
+
+Use it when you want Wave to:
+
+- pull guardrail or findings context for a project
+- filter that context down to the implementation-owned paths in the current wave
+- persist the normalized result as a runtime artifact
+- fail closure automatically when the fetch fails or matched findings cross a configured severity threshold
+
+## Modes
+
+Wave supports three Corridor modes under `externalProviders.corridor`:
+
+```json
+{
+  "externalProviders": {
+    "corridor": {
+      "enabled": true,
+      "mode": "hybrid",
+      "baseUrl": "https://app.corridor.dev/api",
+      "apiTokenEnvVar": "CORRIDOR_API_TOKEN",
+      "apiKeyFallbackEnvVar": "CORRIDOR_API_KEY",
+      "teamId": "corridor-team-id",
+      "projectId": "corridor-project-id",
+      "severityThreshold": "critical",
+      "findingStates": ["open", "potential"],
+      "requiredAtClosure": true
+    }
+  }
+}
+```
+
+- `direct`
+  Wave calls Corridor from the repo runtime with `CORRIDOR_API_TOKEN` or the fallback `CORRIDOR_API_KEY`.
+- `broker`
+  Wave calls an owned `wave-control` deployment with `WAVE_API_TOKEN`, and that service uses deployment-owned Corridor credentials.
+- `hybrid`
+  Wave tries the owned `wave-control` broker first and falls back to direct auth if broker setup or broker delivery fails.
+
+Notes:
+
+- direct mode requires both `teamId` and `projectId` in config; the live fetches use `projectId`, while `teamId` keeps the project identity explicit in repo config
+- broker mode requires an owned Wave Control endpoint; the packaged default endpoint intentionally rejects Corridor brokering
+- if `findingStates` is omitted or set to `[]`, Wave does not filter by finding state and the provider may return all states
+- if you only want active findings, set `findingStates` explicitly, for example `["open", "potential"]`
+
+## What Wave Matches
+
+Wave does not send every file in the repo to Corridor matching.
+
+The runtime builds the relevant path set from implementation-owned paths in the current wave:
+
+- security reviewers are excluded
+- design stewards are excluded
+- integration, documentation, and `cont-QA` owners are excluded
+- `cont-EVAL` only contributes owned paths when that agent is implementation-owning
+- `.tmp/` paths are excluded
+- `docs/` paths are excluded
+- `.md` and `.txt` files are excluded
+
+That means Corridor is aimed at code and implementation-owned assets, not shared-plan markdown or generated launcher state.
+
+Matching is path-prefix based:
+
+- an exact file match counts
+- a finding under a matched owned directory also counts
+- unmatched findings remain in the upstream provider but are dropped from the normalized Wave artifact
+
+## Generated Artifact
+
+Wave writes the normalized Corridor artifact to:
+
+- `.tmp/<lane>-wave-launcher/security/wave-<n>-corridor.json`
+- `.tmp/projects/<projectId>/<lane>-wave-launcher/security/wave-<n>-corridor.json` for explicit projects
+
+Representative shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "wave": 7,
+  "lane": "main",
+  "projectId": "app",
+  "providerMode": "broker",
+  "source": "wave-control-broker",
+  "requiredAtClosure": true,
+  "severityThreshold": "critical",
+  "fetchedAt": "2026-03-29T12:00:00.000Z",
+  "relevantOwnedPaths": ["src/auth", "src/session"],
+  "guardrails": [{ "id": "r1", "name": "No secrets" }],
+  "matchedFindings": [
+    {
+      "id": "f1",
+      "title": "Hardcoded token",
+      "affectedFile": "src/auth/token.ts",
+      "severity": "critical",
+      "state": "open",
+      "matchedOwnedPaths": ["src/auth"]
+    }
+  ],
+  "blockingFindings": [
+    {
+      "id": "f1",
+      "title": "Hardcoded token",
+      "affectedFile": "src/auth/token.ts",
+      "severity": "critical",
+      "state": "open",
+      "matchedOwnedPaths": ["src/auth"]
+    }
+  ],
+  "blocking": true,
+  "error": null
+}
+```
+
+Important fields:
+
+- `providerMode`: the configured mode after runtime resolution
+- `source`: the actual fetch source such as direct Corridor API or owned Wave Control broker
+- `relevantOwnedPaths`: the implementation-owned paths Wave considered eligible for matching
+- `guardrails`: normalized provider-side guardrail/report metadata
+- `matchedFindings`: findings that hit the wave's eligible owned paths
+- `blockingFindings`: matched findings whose severity meets or exceeds `severityThreshold`
+- `blocking`: whether the Corridor result alone is enough to fail the security gate
+- `error`: the fetch or broker error when the load failed
+
+If the wave has no eligible implementation-owned paths, Wave still writes a successful artifact with `blocking: false` and a `detail` explaining that nothing qualified for matching.
+
+## Closure Behavior
+
+Corridor is evaluated before security review finishes.
+
+The security gate behaves like this:
+
+1. If Corridor is disabled, Wave ignores it.
+2. If Corridor is enabled and the fetch fails:
+   - `requiredAtClosure: true` turns that into `corridor-fetch-failed`
+   - `requiredAtClosure: false` keeps the failure visible in summaries without hard-failing the gate
+3. If Corridor loads and matched findings meet the configured threshold:
+   - the gate fails as `corridor-blocked`
+4. If Corridor loads cleanly:
+   - security review still runs and still owns the human-readable report plus `[wave-security]`
+
+That separation matters:
+
+- Corridor provides machine-readable blocking evidence
+- the security reviewer still provides the threat-model-first narrative review, approvals, and final marker
+- `concerns` from the human reviewer remain advisory, while `blocked` from either the reviewer or Corridor stops closure before integration
+
+Matched Corridor findings are also copied into the generated security and integration summaries, so they remain visible even when the human reviewer reports advisory concerns rather than a hard block.
+
+## Broker Mode Through Wave Control
+
+In broker mode, the repo runtime sends a normalized request to:
+
+- `POST /api/v1/providers/corridor/context`
+
+The request body contains:
+
+- `projectId`: the active Wave project id
+- `wave`: current wave number
+- `ownedPaths`: the filtered implementation-owned paths
+- `severityThreshold`
+- `findingStates`
+
+The owned `wave-control` deployment then:
+
+- looks up the Wave project id inside `WAVE_BROKER_CORRIDOR_PROJECT_MAP`
+- fetches Corridor reports and findings with the deployment-owned `WAVE_BROKER_CORRIDOR_API_TOKEN`
+- returns the same normalized shape Wave would have produced in direct mode
+
+Example mapping:
+
+```json
+{
+  "app": {
+    "teamId": "corridor-team-uuid",
+    "projectId": "corridor-project-uuid"
+  }
+}
+```
+
+Broker mode requirements:
+
+- `waveControl.endpoint` must point at an owned Wave Control deployment, not the packaged default endpoint
+- Wave must have a bearer token, normally `WAVE_API_TOKEN`
+- the service deployment must enable Corridor brokering with `WAVE_BROKER_OWNED_DEPLOYMENT=true`, `WAVE_BROKER_ENABLE_CORRIDOR=true`, `WAVE_BROKER_CORRIDOR_API_TOKEN`, and `WAVE_BROKER_CORRIDOR_PROJECT_MAP`
+
+## Prompt And Summary Surfaces
+
+When Corridor loads during a live run, Wave also projects a compact text summary into the generated runtime context. That summary includes:
+
+- the actual source used
+- whether Corridor is currently blocking
+- the configured threshold
+- matched finding count
+- up to five blocking findings
+
+The same Corridor result then appears in:
+
+- the generated security summary
+- the integration summary
+- the trace bundle's copied `corridor.json`
+
+This keeps security context visible to humans without turning the provider response into the sole authority.
+
+## Recommended Pattern
+
+For most repos:
+
+- use `hybrid` if you want an owned Wave Control deployment in normal operation but still want direct-repo fallback during outages or incomplete broker setup
+- set `findingStates` explicitly if you only want open or potential findings considered live
+- leave `requiredAtClosure` enabled when Corridor is meant to be part of the actual release gate
+- keep a report-owning security reviewer in the wave; Corridor should strengthen that review, not replace it
+
+See [runtime-config/README.md](./runtime-config/README.md) for the config keys, [wave-control.md](./wave-control.md) for the owned broker surface, and [coordination-and-closure.md](./coordination-and-closure.md) for the closure-stage gate ordering.

package/docs/reference/npmjs-token-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-The current `0.9.1` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.9.2` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -48,6 +48,6 @@ If this repo later needs private npm dependencies during CI, consider a separate
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
 4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
-5. Push the release commit and release tag, for example `v0.9.1`.
+5. Push the release commit and release tag, for example `v0.9.2`.
 6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
 7. Verify the npmjs publish completes successfully for the tagged source.

package/docs/reference/package-publishing-flow.md

@@ -15,7 +15,7 @@ Release preparation happens in the repository itself:
 - update release-surface docs and fixtures
 - validate the repo
 - merge the release changes to `main`
-- push a version tag such as `v0.9.1`
+- push a version tag such as `v0.9.2`
 
 Registry publishing happens in GitHub Actions after the tag push:
 
@@ -127,9 +127,9 @@ This repository protects `main`, so release changes must land through a pull req
 Typical git flow:
 
 ```bash
-git checkout -b release/0.9.1
-git push -u origin release/0.9.1
-gh pr create --base main --head release/0.9.1
+git checkout -b release/0.9.2
+git push -u origin release/0.9.2
+gh pr create --base main --head release/0.9.2
 gh pr merge <pr-number> --merge --delete-branch
 ```
 
@@ -138,13 +138,13 @@ gh pr merge <pr-number> --merge --delete-branch
 After the release commit is on `main`, push the version tag:
 
 ```bash
-git tag v0.9.1
-git push origin v0.9.1
+git tag v0.9.2
+git push origin v0.9.2
 ```
 
 That tag push is the event that starts both publishing workflows.
 
-The tag must match the checked-in package version exactly. Example: if `package.json.version` is `0.9.1`, the pushed tag must be `v0.9.1`.
+The tag must match the checked-in package version exactly. Example: if `package.json.version` is `0.9.2`, the pushed tag must be `v0.9.2`.
 
 ## GitHub Actions Workflows
 
@@ -212,9 +212,9 @@ Expected result after a successful publish:
 
 ```json
 {
-  "version": "0.9.1",
+  "version": "0.9.2",
   "dist-tags": {
-    "latest": "0.9.1"
+    "latest": "0.9.2"
   }
 }
 ```
@@ -231,8 +231,8 @@ If a tag-triggered publish fails before the package is actually published, the f
 Example:
 
 ```bash
-git tag -f v0.9.1 <fixed-commit>
-git push origin refs/tags/v0.9.1 --force
+git tag -f v0.9.2 <fixed-commit>
+git push origin refs/tags/v0.9.2 --force
 ```
 
 Use that only before the package is live on npmjs. Once npmjs has accepted a version, do not try to republish the same version; cut a new version instead.