@chllming/wave-orchestration 0.9.1 → 0.9.2

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.

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

@@ -8,6 +8,7 @@ Use it when you need the full supported surface for:
 - `defaultProject` and `projects.<projectId>`
 - `lanes.<lane>.executors`
 - `waveControl`
+- `externalProviders`
 - `executors.profiles.<profile>`
 - per-agent `### Executor` blocks inside a wave file
 
@@ -190,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.1.md](../../guides/recommendations-0.9.1.md) for the recommended `0.9.1` operating stance that combines advisory turn budgets with softer non-proof coordination states
+- 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
 
 ## Runtime Pages
 
@@ -202,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.1`:
+Packaged defaults in `@chllming/wave-orchestration@0.9.2`:
 
 - `endpoint`: `https://wave-control.up.railway.app/api/v1`
 - `reportMode`: `metadata-only`
@@ -219,7 +220,10 @@ Supported top-level fields:
 | `endpoint` | string | `https://wave-control.up.railway.app/api/v1` | Base URL for the Railway-hosted `services/wave-control` API |
 | `workspaceId` | string | derived from repo path | Stable workspace identity used across runs |
 | `projectId` | string | resolved project id | Stable project identity used for cross-workspace reporting and filtering |
-| `authTokenEnvVar` | string | `WAVE_CONTROL_AUTH_TOKEN` | Environment variable name holding the bearer token |
+| `authTokenEnvVar` | string | `WAVE_API_TOKEN` | Primary environment variable name holding the bearer token |
+| `authTokenEnvVars` | string[] | `["WAVE_API_TOKEN", "WAVE_CONTROL_AUTH_TOKEN"]` | Ordered fallback env var list consulted when Wave resolves a bearer token for owned Wave Control routes |
+| `credentialProviders` | string[] | `[]` | Allowlisted runtime credential leases requested from an owned Wave Control deployment before executor launch. Supported values: `openai`, `anthropic` |
+| `credentials` | `{ id, envVar }[]` | `[]` | Arbitrary per-user credential leases requested from an owned Wave Control deployment before executor launch |
 | `reportMode` | string | `metadata-only` | `disabled`, `metadata-only`, `metadata-plus-selected`, or `full-artifact-upload` |
 | `uploadArtifactKinds` | string[] | selected proof/trace/benchmark kinds | Artifact classes eligible for body upload when an artifact's upload policy requests a body |
 | `requestTimeoutMs` | integer | `5000` | Per-batch network timeout |
@@ -232,6 +236,8 @@ Supported top-level fields:
 
 Lane overrides may refine the same keys under `lanes.<lane>.waveControl` or `projects.<projectId>.lanes.<lane>.waveControl`.
 
+Wave resolves the Wave Control bearer token from `authTokenEnvVars` when that list is present. Otherwise it resolves `authTokenEnvVar` first and keeps `WAVE_CONTROL_AUTH_TOKEN` as a compatibility fallback.
+
 One-run override:
 
 - `wave launch --no-telemetry` disables Wave Control queueing and remote delivery for that launcher invocation without changing the repo config.
@@ -246,6 +252,8 @@ Example:
     "endpoint": "https://wave-control.up.railway.app/api/v1",
     "workspaceId": "wave-main",
     "projectId": "app",
+    "credentialProviders": ["openai"],
+    "credentials": [{ "id": "github_pat", "envVar": "GITHUB_TOKEN" }],
     "reportMode": "metadata-only",
     "uploadArtifactKinds": [
       "trace-run-metadata",
@@ -261,6 +269,56 @@ Runtime-emitted Wave Control events also attach:
 - `orchestratorId` from the active launcher or resident orchestrator
 - `runtimeVersion` from the installed Wave package metadata
 
+## External Providers
+
+Wave can resolve third-party auth directly in the repo runtime or through an owned Wave Control broker.
+
+```json
+{
+  "externalProviders": {
+    "context7": {
+      "mode": "direct",
+      "apiKeyEnvVar": "CONTEXT7_API_KEY"
+    },
+    "corridor": {
+      "enabled": false,
+      "mode": "direct",
+      "baseUrl": "https://app.corridor.dev/api",
+      "apiTokenEnvVar": "CORRIDOR_API_TOKEN",
+      "apiKeyFallbackEnvVar": "CORRIDOR_API_KEY",
+      "teamId": "team-id-for-direct-mode",
+      "projectId": "project-id-for-direct-mode",
+      "severityThreshold": "critical",
+      "findingStates": ["open", "potential"],
+      "requiredAtClosure": true
+    }
+  }
+}
+```
+
+- `direct`: use repo/runtime env vars directly
+- `broker`: use the owned Wave Control endpoint with `WAVE_API_TOKEN`
+- `hybrid`: try the broker first, then fall back to direct auth if broker setup fails or a broker request fails at runtime
+- direct Corridor mode requires both `teamId` and `projectId` in config; broker mode instead requires a matching `WAVE_BROKER_CORRIDOR_PROJECT_MAP` entry on the owned Wave Control deployment
+- Wave auto-loads an allowlisted repo-root `.env.local` for `CONTEXT7_API_KEY`, `CORRIDOR_API_TOKEN`, `CORRIDOR_API_KEY`, `WAVE_API_TOKEN`, and `WAVE_CONTROL_AUTH_TOKEN`
+- `wave doctor` now warns or fails early when brokered providers target the packaged default endpoint or no Wave Control auth token is available
+- Context7 remains fail-open
+- Corridor writes `.tmp/<lane>-wave-launcher/security/wave-<n>-corridor.json`, filters findings down to the wave's implementation-owned non-doc, non-`.tmp/`, non-markdown paths, and can fail closure when the fetch fails or matched findings meet the configured threshold
+- Broker mode is intended for self-hosted or team-owned Wave Control only; the packaged default endpoint is rejected as a provider-secret proxy
+- if `findingStates` is omitted or set to `[]`, Wave does not apply a state filter and the provider may return all states
+- for the full Corridor lifecycle, including broker mapping, generated artifact shape, and gate semantics, see [../corridor.md](../corridor.md)
+
+`waveControl.credentialProviders` is related but separate from `externalProviders`:
+
+- use `externalProviders.context7` and `externalProviders.corridor` for brokered or direct API access during planning / closure flows
+- use `waveControl.credentialProviders` only when an executor needs env vars leased into its runtime
+- use `waveControl.credentials` when an executor needs arbitrary user-owned secrets leased into env vars such as `GITHUB_TOKEN` or `NPM_TOKEN`
+- only `openai` and `anthropic` are valid leased providers today
+- `context7` and `corridor` remain broker-only and are never returned as raw env secrets
+- `waveControl.credentials[*].id` must match `/^[a-z0-9][a-z0-9._-]*$/`
+- `waveControl.credentials[*].envVar` must match `/^[A-Z_][A-Z0-9_]*$/`
+- when provider or arbitrary credentials are leased, Wave injects them into the live executor environment and redacts those keys in `launch-preview.json`
+
 Those fields are queryable in the `wave-control` service alongside `workspaceId`,
 `projectId`, `runKind`, `runId`, `lane`, and benchmark ids.
 

package/docs/reference/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the shipped 0.9.1 authored surface, including the optional design-role path."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.9.2 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the shipped `0.9.1` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.9.2` authored Wave surface.
 
 The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
@@ -17,7 +17,7 @@ All example `.tmp/main-wave-launcher/...` paths assume the implicit default proj
   Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.9.1` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.9.2` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 - [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
   Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
@@ -46,7 +46,7 @@ All example `.tmp/main-wave-launcher/...` paths assume the implicit default proj
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened through `0.9.1`:
+Together these samples cover the main surfaces added or hardened through `0.9.2`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -184,7 +184,7 @@ Adapt more aggressively when:
 ## Suggested Reading Order
 
 1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
-2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.9.1` surface.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.9.2` surface.
 3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
 4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
 5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.

package/docs/reference/skills.md

@@ -124,7 +124,7 @@ Top-level and lane-local skill attachment use the same shape:
 
 Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
 
-Optional design workers in the shipped `0.9.1` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+Optional design workers in the shipped `0.9.2` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
 
 Long-running agents that should stay resident and react only to orchestrator signal changes can add `signal-hygiene` explicitly in `### Skills`. That bundle is not auto-attached and is not meant for normal one-shot implementation agents.