@chllming/wave-orchestration 0.9.0 → 0.9.2

package/docs/plans/sandbox-end-state-architecture.md

@@ -0,0 +1,153 @@
+# Sandbox End-State Architecture
+
+This document is the sandbox-runtime companion to [end-state-architecture.md](./end-state-architecture.md). The core architecture still applies: the canonical authority set remains wave definitions, the coordination log, and the control-plane event log. This page narrows that model to the execution environments that impose short-lived `exec` sessions, process ceilings, or terminal instability.
+
+The goal is straightforward: sandbox client commands must stay short and disposable, while long-running wave ownership moves to a durable supervisor that can survive launcher exit, sandbox timeout, and terminal churn.
+
+For the operator-facing setup flow in LEAPclaw, OpenClaw, Nemoshell, Docker, and similar environments, read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md). This page is the deeper design and authority-model reference.
+
+---
+
+## Problem Statement
+
+Sandboxed runtimes have failure modes that the generic architecture does not need to describe in detail:
+
+- the sandbox `exec` session may have a wall-clock timeout that is much shorter than a real wave
+- bursty `spawnSync` and `tmux` probes can hit `EAGAIN`, `EMFILE`, or related process pressure limits
+- the launcher process can die before child agents finish, leaving orphaned sessions and ambiguous status
+- a missing `tmux` session is not enough evidence that the actual agent process failed
+
+The shipped runtime now has an initial async supervisor wrapper plus forwarded closure-gap handling, but it does not yet satisfy the full sandbox ownership model described here.
+
+---
+
+## Target Command Model
+
+Sandbox-facing commands should follow an async submit/observe pattern:
+
+- `wave submit [launcher options]`
+  Validate the request, persist a run request, print a `runId`, and exit quickly.
+- `wave supervise`
+  Long-running daemon command that owns launch, monitoring, retry, adoption, and cleanup. This command is not intended to be bound to a short sandbox `exec` lifetime.
+- `wave status --run-id <id>`
+  Read canonical supervisor state for a run.
+- `wave wait --run-id <id> --timeout-seconds <n>`
+  Observe until a state change or timeout. Timing out never cancels the run.
+- `wave attach --run-id <id>`
+  Optional operator projection surface for `tmux` or another terminal UI. This is not a liveness authority.
+
+Compatibility rules:
+
+- `wave launch` remains the canonical full launcher surface for direct local execution and dry-run validation.
+- `wave autonomous` should submit and observe wave execution when it is used in sandbox-oriented flows.
+- `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` are the preferred sandbox-facing surface, even while some internals remain partial.
+
+---
+
+## Canonical Authority In Sandboxed Runs
+
+The canonical authority set does not change, but sandbox supervision adds one more durable runtime layer:
+
+- wave definitions remain authoritative for declared work, closure roles, proof artifacts, and task contracts
+- coordination and control-plane logs remain authoritative for workflow, lifecycle, proof, and blocker state
+- supervisor run state becomes the canonical record of daemon-owned runtime observation for a submitted run
+
+The supervisor-owned state should converge on this per-run structure under `.tmp/<lane>-wave-launcher/supervisor/runs/<runId>/`:
+
+- `request.json`
+  Immutable submitted request.
+- `state.json`
+  Current daemon-owned run snapshot, including `runId`, `status`, `submittedAt`, `startedAt`, `completedAt`, `launcherPid`, `supervisorId`, `leaseExpiresAt`, `terminalDisposition`, and the latest observed launcher status.
+- `events.jsonl`
+  Supervisor-local observation history for adoption, retries, reconciliation, and cleanup decisions.
+- `launcher-status.json`
+  Canonical launcher completion status written atomically by the detached launcher wrapper.
+- `launcher.log`
+  Human-facing log stream only.
+- `agents/<agentId>.runtime.json`
+  Agent runtime observation record with fields such as `pid`, `pgid`, `attempt`, `startedAt`, `lastHeartbeatAt`, `exitCode`, `exitReason`, `statusPath`, and optional projection metadata like `tmuxSessionName`.
+
+Authority rules:
+
+- `tmux` is projection-only
+- dashboards, summaries, inboxes, and board markdown remain projections only
+- missing `tmux` state cannot by itself fail a run and is warning-only telemetry
+- pid checks, heartbeats, and atomic status files outrank terminal presence for liveness
+
+---
+
+## Daemon Ownership, Adoption, And Process Control
+
+The end state requires one daemon-owned control path for long-running work:
+
+1. `wave submit` writes the request and exits.
+2. `wave supervise` claims or renews a lease, launches work, and records observed runtime facts.
+3. `wave status` and `wave wait` read canonical state only.
+4. If the daemon dies, a later daemon instance can adopt active runs after lease expiry and continue observation without relaunching healthy agents.
+
+The daemon must own:
+
+- bounded process launch concurrency
+- async retry with jittered backoff for `EAGAIN`, `EMFILE`, and `ENFILE`
+- orphan adoption after stale lease detection
+- conservative orphan cleanup only after lease expiry, stale heartbeat, and failed pid confirmation
+- reconciliation between launcher status files, live pid state, and control-plane events
+
+The daemon must not depend on:
+
+- repeated `spawnSync("tmux", "list-sessions")` calls in the steady-state wait loop
+- one sandbox client process staying alive for the full wave duration
+- terminal presence as the source of truth for agent or wave health
+
+---
+
+## Closure Semantics For Forwarded Proof Gaps
+
+Closure staging still runs in the normal order:
+
+`implementation + proof -> cont-EVAL -> security/A7 -> integration/A8 -> docs/A9 -> cont-QA/A0`
+
+Sandbox stability does not change closure authority, but the daemon must preserve one special case:
+
+- `wave-proof-gap` from a closure-stage agent is a forwarded soft blocker, not an immediate full-wave stop
+
+Forwarding rules:
+
+- if A7 returns `wave-proof-gap`, the daemon still dispatches A8, A9, and A0 with the gap included as structured input
+- if A8 returns `wave-proof-gap`, the daemon still dispatches A9 and A0
+- if A9 returns `wave-proof-gap`, the daemon still dispatches A0
+- later closure agents must evaluate the currently available artifacts and report what is true; they must not refuse to run only because an earlier closure-stage agent reported `wave-proof-gap`
+- the final wave disposition remains blocked until the forwarded closure gaps are resolved
+
+Non-forwardable closure failures remain hard stops. Examples include malformed outputs, missing proof envelopes, explicit integration blockers, or invalid marker formats.
+
+---
+
+## Current Implementation Status
+
+Already landed:
+
+- `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` exist as a file-backed async wrapper over the existing launcher
+- supervisor state now includes lease-backed daemon ownership, `events.jsonl`, exact lane-scoped lookup, and detached launcher-status reconciliation
+- agent runtime records now capture per-agent pid, heartbeat, runner metadata, terminal disposition, and attach or log-follow metadata for supervisor-owned runs
+- `wave autonomous` now submits and observes single-wave runs through the supervisor surface instead of binding them to one blocking launcher subprocess
+- closure-stage `wave-proof-gap` forwarding now continues later closure stages and records the blocker instead of failing the whole sweep immediately
+- retry planning now invalidates later closure reuse from the earliest forwarded closure-gap stage
+- agent execution now uses detached process runners by default, which lowers tmux session churn and memory pressure in wide fan-outs; tmux remains dashboard-only and `wave attach --agent` falls back to log following when no live session exists
+- launcher progress journaling now lets the supervisor recover finalized runs and safely resume the active wave without a repo-wide rescan
+
+Still missing for the true end state:
+
+- broader resume semantics beyond “restart the active wave with preserved control state”; recovery can now use finalized progress journals and canonical run-state completion, but multi-wave and auto-next recovery is still conservative
+- fully tmux-free live dashboard projection; dashboard attach now falls back to the last written dashboard file, but live dashboard sessions still use tmux today
+- full success inference from canonical runtime facts alone; the daemon still refuses to synthesize success from agent runtime files without either finalized progress or canonical run-state completion
+
+---
+
+## Remaining Gap Plan
+
+1. Implement supervisor lease, heartbeat, and stale-lock reclamation so a restarted daemon can adopt active runs without relaunching healthy work.
+2. Move liveness authority to pid, heartbeat, and atomic status files; keep `tmux` as projection-only and remove sync terminal probes from steady-state monitoring.
+3. Materialize supervisor events and per-agent runtime records as canonical daemon state, not only ad hoc wrapper files.
+4. Extend forwarded closure-gap handling into retry planning so the earliest forwarded gap invalidates later closure outputs for reuse while still preserving them for operator evidence.
+5. Converge sandbox-facing entrypoints so `submit/status/wait` become the default operator path and `autonomous` no longer owns a multi-hour blocking launcher process.

package/docs/reference/cli-reference.md

@@ -13,6 +13,8 @@ When a command targets lane-scoped runtime state, it also accepts `--project <id
 
 - Runtime:
   `wave launch`, `wave autonomous`, and `wave local` cover dry-run validation, live execution, and executor-specific prompt transport.
+- Sandbox async supervision:
+  `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach` provide the sandbox-friendly submit-and-observe surface for long-running waves.
 - Operator control:
   `wave control` is the preferred surface for live status, tasks, reruns, proof bundles, and telemetry.
 - Compatibility and inspection:
@@ -43,7 +45,7 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
 | `--auto-next` | off | Start from next unfinished wave and continue |
 | `--resume-control-state` | off | Preserve the prior auto-generated relaunch plan instead of treating the launch as a fresh wave start |
 | `--executor <id>` | `codex` | Default executor: `codex`, `claude`, `opencode`, `local` |
-| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox isolation level |
+| `--codex-sandbox <mode>` | lane config | Codex sandbox isolation override; falls back to `danger-full-access` only when config is unset |
 | `--timeout-minutes <n>` | `240` | Max minutes to wait per wave |
 | `--max-retries-per-wave <n>` | `1` | Relaunch failed agents per wave |
 | `--agent-rate-limit-retries <n>` | `2` | Per-agent retries for 429 errors |
@@ -51,9 +53,9 @@ Closure-role bindings do not have a CLI override surface. When a wave file decla
 | `--agent-rate-limit-max-delay-seconds <n>` | `180` | Max backoff delay for 429 |
 | `--agent-launch-stagger-ms <n>` | `1200` | Delay between agent launches |
 | `--terminal-surface <mode>` | `vscode` | `tmux`, `vscode`, or `none` |
-| `--no-dashboard` | off | Disable per-wave tmux dashboard |
-| `--cleanup-sessions` | on | Kill lane tmux sessions after each wave |
-| `--keep-sessions` | off | Keep lane tmux sessions |
+| `--no-dashboard` | off | Disable the per-wave dashboard projection session |
+| `--cleanup-sessions` | on | Kill lane tmux dashboard and projection sessions after each wave |
+| `--keep-sessions` | off | Keep lane tmux dashboard and projection sessions |
 | `--keep-terminals` | off | Keep temporary terminal entries |
 | `--orchestrator-id <id>` | generated | Stable orchestrator identity |
 | `--orchestrator-board <path>` | default board path | Write coordination-board updates to a specific shared board |
@@ -80,7 +82,7 @@ wave autonomous [options]
 | `--project <id>` | config default | Project id |
 | `--lane <name>` | `main` | Lane name |
 | `--executor <id>` | lane config | `codex`, `claude`, or `opencode` (not `local`) |
-| `--codex-sandbox <mode>` | `danger-full-access` | Codex sandbox mode |
+| `--codex-sandbox <mode>` | lane config | Codex sandbox override passed to launcher; falls back to `danger-full-access` only when config is unset |
 | `--timeout-minutes <n>` | `240` | Per-wave timeout passed to launcher |
 | `--max-retries-per-wave <n>` | `1` | Per-wave relaunches inside launcher |
 | `--max-attempts-per-wave <n>` | `1` | External attempts per wave |
@@ -91,9 +93,65 @@ wave autonomous [options]
 | `--orchestrator-id <id>` | `<lane>-autonomous` | Orchestrator identity |
 | `--resident-orchestrator` | off | Launch resident orchestrator for each wave |
 | `--dashboard` | off | Enable dashboards |
-| `--keep-sessions` | off | Keep tmux sessions between waves |
+| `--keep-sessions` | off | Keep tmux dashboard and projection sessions between waves |
 | `--keep-terminals` | off | Keep terminal entries between waves |
 
+When you run Wave in a sandbox with short-lived `exec` sessions, prefer the async supervisor surface instead of binding the whole run to one long-lived `wave autonomous` client process. The end-state sandbox model is documented in [../plans/sandbox-end-state-architecture.md](../plans/sandbox-end-state-architecture.md).
+
+## wave submit
+
+Submit a launcher request for daemon-owned execution and return quickly with a `runId`.
+
+``` 
+wave submit [launcher options] [--json]
+```
+
+Current implementation status: this is a file-backed wrapper over `wave-launcher.mjs` with daemon leases, exact-context lookup, launcher-status reconciliation, progress journaling, and process-backed agent execution. It is the preferred sandbox-facing entrypoint for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar short-lived exec environments, even though the broader daemon convergence described in [../plans/sandbox-end-state-architecture.md](../plans/sandbox-end-state-architecture.md) is still conservative in some recovery paths.
+
+`wave submit` accepts the same launcher options you would pass to `wave launch`, for example `--project`, `--lane`, `--start-wave`, `--end-wave`, `--executor`, `--codex-sandbox`, `--timeout-minutes`, `--agent-launch-stagger-ms`, `--resident-orchestrator`, `--no-dashboard`, and `--dry-run`. Use `--json` when you want a structured payload containing `runId`, `project`, `lane`, optional `adhocRunId`, and `statePath`.
+
+For concrete setup guidance, read [../guides/sandboxed-environments.md](../guides/sandboxed-environments.md).
+
+## wave supervise
+
+Run the supervisor loop that claims queued submitted runs and reconciles launcher status.
+
+```
+wave supervise [--project <id>] [--lane <name>] [--once]
+```
+
+Use `--once` for a single reconciliation pass in tests or wrapper scripts. The shipped daemon now renews a lease, reconciles detached launcher status, and can adopt already-running submitted runs from the same lane-scoped supervisor root.
+
+## wave status
+
+Read the current supervisor-owned state for a submitted run.
+
+```
+wave status --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] [--json]
+```
+
+Current implementation status: reads the thin file-backed supervisor state from the exact lane-scoped supervisor root. `--project` and `--lane` are required so status does not guess across unrelated state trees.
+
+## wave wait
+
+Wait for a submitted run to reach terminal state or until the wait timeout expires.
+
+```
+wave wait --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] [--timeout-seconds <n>] [--json]
+```
+
+`wave wait` is observational only. Timing out does not cancel or kill the underlying run.
+
+## wave attach
+
+Attach to a projection for a submitted run.
+
+```
+wave attach --run-id <id> --project <id> --lane <name> [--adhoc-run <id>] (--agent <id> | --dashboard)
+```
+
+`--agent <id>` attaches to a live session only when the runtime record explicitly exposes one; otherwise it follows the recorded log, or prints the recent log tail if the agent is already terminal. `--dashboard` reuses the current lane dashboard attach surface and falls back to the last written dashboard file when no live dashboard session exists. Missing projections are treated as operator errors, not as run-health failures.
+
 ## wave control
 
 Unified operator control surface. Preferred over legacy `wave coord`, `wave retry`, and `wave proof`.
@@ -114,6 +172,10 @@ The JSON payload now includes:
   Versioned wave-level signal state for wrappers and external operators.
 - `signals.agents`
   Versioned per-agent signal state, including `shouldWake` plus any observed ack metadata.
+- `supervisor`
+  The most relevant lane-scoped supervisor run for this wave, including degraded states such as `launcher-lost-agents-running`, recovery fields such as `sessionBackend`, `recoveryState`, and `resumeAction`, plus any recorded per-agent runtime summary.
+- `forwardedClosureGaps`
+  Earliest-first forwarded `wave-proof-gap` records from the relaunch plan, including the stage key, originating agent, attempt, detail, and downstream closure targets.
 
 Starter repos also include `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over this JSON payload. They use exit `0` for completed, `20` for input-required, `40` for failed, and `30` from `wave-watch.sh --until-change` when the signal changed but the wave stayed active. For the full wrapper contract, read [../guides/signal-wrappers.md](../guides/signal-wrappers.md).
 
@@ -505,6 +567,8 @@ wave dashboard --dashboard-file <path> [--project <id>] [--lane <lane>] [--messa
 wave dashboard --project <id> --lane <lane> --attach current|global
 ```
 
+`wave dashboard --attach current|global` attaches to the live dashboard session when one exists; otherwise it follows the last written dashboard JSON for that target.
+
 ## Workspace Commands
 
 **Initialize workspace:**
@@ -565,7 +629,7 @@ Interactive draft currently offers worker role kinds:
 - `research`
 - `security`
 
-Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.9.0` 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.0` recommendation on when to keep records blocking versus when to downgrade them to `soft`, `stale`, or `advisory`, see [../guides/recommendations-0.9.0.md](../guides/recommendations-0.9.0.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.

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/github-packages-setup.md

@@ -3,7 +3,7 @@
 Use this page only if you intentionally want the legacy GitHub Packages install path.
 
 GitHub's npm registry still requires authentication for installs from `npm.pkg.github.com`, even when the package and backing repository are public.
-This is now the optional authenticated fallback path. The primary public install path is npmjs. Maintainer npm publishing setup is documented in [npmjs-trusted-publishing.md](./npmjs-trusted-publishing.md).
+This is now the optional authenticated fallback path. The primary public install path is npmjs. Maintainer npm publishing setup is documented in [npmjs-token-publishing.md](./npmjs-token-publishing.md).
 
 ## `.npmrc`
 

package/docs/reference/migration-0.2-to-0.5.md

@@ -1,12 +1,12 @@
 ---
 title: "Wave Orchestration Migration Guide: 0.2 to 0.5"
-summary: "How to migrate a repository from the earlier 0.2 wave baseline to the current post-roadmap Wave model."
+summary: "How to migrate a repository from the earlier 0.2 wave baseline to the current Wave model."
 ---
 
 # Wave Orchestration Migration Guide: 0.2 to 0.5
 
 This guide explains how to migrate a repository from the earlier Wave
-Orchestration 0.2 baseline to the current post-roadmap Wave model.
+Orchestration 0.2 baseline to the current Wave model.
 
 Current mainline note:
 
@@ -20,10 +20,11 @@ It uses two concrete references:
 - the 0.2-style baseline in the sibling `~/slowfast.ai` repo
 - the current target shape in this standalone `wave-orchestration` repo
 
-This is a migration guide for the current architecture described in
-[Roadmap](../roadmap.md), not just a changelog of whatever happens to be landed
-in one point-in-time package build. This document is about the shipped runtime
-shape, not only the semver label.
+This is a migration guide for the current shipped architecture and release
+direction described across [docs/architecture/README.md](../architecture/README.md)
+and [Roadmap](../roadmap.md), not just a changelog of whatever happens to be
+landed in one point-in-time package build. This document is about the shipped
+runtime shape, not only the semver label.
 
 ## Baseline And Target
 
@@ -34,7 +35,8 @@ Use these files as the concrete examples while migrating:
 - 0.2 baseline wave example: `~/slowfast.ai/docs/plans/waves/wave-7.md`
 - current target config: [wave.config.json](../../wave.config.json)
 - current target sample wave: [wave-0.md](../plans/waves/wave-0.md)
-- current target architecture: [roadmap.md](../roadmap.md)
+- current target architecture: [architecture/README.md](../architecture/README.md)
+- current release direction: [roadmap.md](../roadmap.md)
 - current package workflow: [README.md](../../README.md)
 
 The migration is intentionally evolutionary: