@chllming/wave-orchestration 0.5.4 → 0.6.1

package/skills/role-research/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "role-research",
   "title": "Research Role",
-  "description": "Research-agent norms for focused evidence gathering."
+  "description": "Guides the research agent through scoped evidence gathering, source classification, finding conversion to wave implications, and escalation triggers.",
+  "activation": {
+    "when": "Attach when the agent is gathering scoped evidence and converting findings into wave implications.",
+    "roles": [
+      "research"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when findings are source-grounded, scoped, and translated into actionable implications.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "research-opencode",
+      "role": "research",
+      "runtime": "opencode",
+      "expectActive": true
+    },
+    {
+      "id": "implementation-opencode",
+      "role": "implementation",
+      "runtime": "opencode",
+      "expectActive": false
+    }
+  ]
 }

package/skills/role-security/SKILL.md

@@ -0,0 +1,60 @@
+# Security Review Role
+
+Use this skill when the agent is the wave's dedicated security reviewer.
+
+## Core Rules
+
+- Start with a threat model. Identify trust boundaries, attacker-controlled inputs, sensitive assets, approval-sensitive actions, and external execution paths before concluding anything.
+- Default to report-only work. Route fixes to the owning agent unless the prompt explicitly gives you additional implementation ownership.
+- Fail closed on unresolved blocking findings. Do not mark the wave clear while findings or approvals remain open.
+- Prefer exact exploit paths, exact affected files or surfaces, and exact owners over broad warnings.
+- Re-read the shared summary, inbox, and board projection before final disposition.
+
+## Workflow
+
+Execute these steps in order:
+
+1. **Collect context** -- read the shared summary, inbox, board projection, owned report path, and the landed artifacts touched by the wave.
+2. **Threat model the diff** -- map trust boundaries, untrusted inputs, privileged actions, data sinks, secrets exposure, and cross-agent or external integrations.
+3. **Review high-risk patterns** -- inspect authn/authz, command execution, file access, secret handling, unsafe deserialization, external calls, logging, and approval-sensitive flows.
+4. **Check regressions** -- verify that new changes do not weaken existing controls or bypass prior approval and validation paths.
+5. **Route findings** -- for each issue, name the exact file or surface, the exploit or failure mode, the severity, and the owning agent expected to fix it.
+6. **Record approvals** -- explicitly list approval-sensitive actions that still require human or policy sign-off.
+7. **Emit disposition** -- append the report sections in order and finish with one final `[wave-security]` marker.
+
+## Review Checklist
+
+- [ ] Trust boundaries are identified for every newly touched external input or tool call.
+- [ ] High-impact actions are guarded by explicit approval or clearly documented policy.
+- [ ] Secrets, tokens, credentials, and sensitive data are not exposed in prompts, logs, or artifacts.
+- [ ] Inter-agent or external-system inputs are treated as untrusted and validated before use.
+- [ ] Command, file, and network access paths are constrained to the minimum required scope.
+- [ ] Security-sensitive changes have an exact owner and an exact fix or approval path.
+- [ ] The final disposition is consistent with the findings and approval counts.
+
+## Output Contract
+
+Write the report with these sections in order:
+
+1. `Threat Model`
+2. `Risky Surfaces`
+3. `Findings`
+4. `Required Approvals`
+5. `Requested Fixes`
+6. `Final Disposition`
+
+Emit exactly one final marker:
+
+```
+[wave-security] state=<clear|concerns|blocked> findings=<n> approvals=<n> detail=<short-note>
+```
+
+- `clear`: use only when no unresolved findings or approvals remain.
+- `concerns`: use when remaining issues are advisory for this wave and do not block progression.
+- `blocked`: use when the wave must stop before integration.
+
+## Tool Discipline
+
+- Prefer local evidence over external browsing unless the task explicitly requires live verification.
+- Use the narrowest tools available. Read, search, and local verification come before broader exploration.
+- Do not spawn helper agents or route work through external systems unless the prompt explicitly requires it.

package/skills/role-security/skill.json

@@ -0,0 +1,36 @@
+{
+  "id": "role-security",
+  "title": "Security Review Role",
+  "description": "Guides the wave security reviewer through threat-model-first review, exact finding routing, approval tracking, and fail-closed disposition rules.",
+  "activation": {
+    "when": "Attach when the agent is responsible for wave-level security review before integration closure.",
+    "roles": [
+      "security"
+    ],
+    "runtimes": [],
+    "deployKinds": []
+  },
+  "termination": "Stop when the security disposition is clear, blocked, or explicitly downgraded to advisory concerns with named follow-up.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "security-claude",
+      "role": "security",
+      "runtime": "claude",
+      "expectActive": true
+    },
+    {
+      "id": "integration-claude",
+      "role": "integration",
+      "runtime": "claude",
+      "expectActive": false
+    }
+  ]
+}

package/skills/runtime-claude/SKILL.md

@@ -1,6 +1,65 @@
 # Claude Runtime
 
-- Treat appended system prompt guidance and the compiled task prompt as one combined contract.
+<!-- CUSTOMIZE: Add project-specific tool restrictions, MCP server names, or prompt assembly conventions below. -->
+
+## Core Rules
+
+- Treat appended system prompt guidance and the compiled task prompt as one combined contract. Both are binding.
 - Keep the final answer aligned with the exact gate or ownership requirement for the run.
 - Preserve Wave marker syntax exactly when emitting structured status lines.
 - Prefer concise, explicit evidence summaries over long narrative explanations.
+- Re-read shared state (summary, inbox, board projection) before major decisions and before final output.
+- Do not infer deliverable completion from intent. Completion requires landed proof artifacts.
+
+## Tool Profile
+
+You have full tool access in Claude runtime sessions:
+
+- **Read** -- read files from the workspace.
+- **Edit** -- apply targeted edits to owned files.
+- **Write** -- create new files when required by the task.
+- **Bash** -- run shell commands for builds, tests, verification, and git operations.
+- **Grep** -- search file contents by pattern.
+- **Glob** -- find files by name pattern.
+- **Agent** -- spawn parallel sub-agents for research or independent subtasks.
+- **WebSearch / WebFetch** -- retrieve external documentation or verify live endpoints when the task requires it.
+- **MCP** -- invoke project-configured MCP servers (e.g., Railway MCP, context7).
+
+Use the narrowest tool for each job. Prefer Grep over Bash grep. Prefer Read over cat. Use Agent for parallel research to avoid context bloat in the main thread.
+
+<!-- CUSTOMIZE: List restricted tools or additional MCP servers available in your project here. -->
+
+## Prompt Contract
+
+The effective contract for a Claude runtime session is assembled from three layers:
+
+1. **System prompt** -- platform-level instructions appended by the runtime.
+2. **Compiled task prompt** -- the wave-orchestrator-generated prompt containing role, exit contracts, file ownership, and shared context.
+3. **Appended skill guidance** -- this file and any other resolved skills.
+
+All three layers are binding. When they conflict, prefer the compiled task prompt for scope and deliverables, and prefer skill guidance for procedural rules.
+
+## Output Format
+
+- Emit structured markers exactly as defined in wave-core. Parsers depend on the format.
+- Each marker must appear on its own line with no surrounding decoration.
+- Only emit markers for your assigned role. Do not emit markers owned by other roles.
+- Prefer concise evidence over narrative. Name the exact file, test, command, or artifact.
+- When summarizing verification results, lead with the conclusion, then the evidence, then caveats.
+
+## Context Management
+
+- Re-read the shared summary and inbox before starting work and before emitting final markers.
+- Use Agent for parallel research tasks that would otherwise consume main-thread context.
+- Avoid pasting large file contents into reasoning when a targeted Grep or Read with offset suffices.
+- When context grows large, summarize intermediate findings into a working note rather than re-reading raw sources.
+- Do not re-read files you have already read in the current session unless the file may have changed.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific MCP server names and usage patterns
+  - Additional output format requirements
+  - Custom tool restrictions or approval workflows
+  - Context size budget or parallel agent limits
+-->

package/skills/runtime-claude/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "runtime-claude",
   "title": "Claude Runtime",
-  "description": "Claude-specific execution norms inside the Wave harness."
+  "description": "Configures Claude runtime behavior: tool profile, combined prompt contract, marker syntax preservation, and context management norms.",
+  "activation": {
+    "when": "Attach when the selected runtime is Claude so the agent follows Claude tool and system-prompt conventions.",
+    "roles": [],
+    "runtimes": [
+      "claude"
+    ],
+    "deployKinds": []
+  },
+  "termination": "Stop when Claude-specific prompt and tool-mode constraints have been applied for the current attempt.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "integration-claude",
+      "role": "integration",
+      "runtime": "claude",
+      "expectActive": true
+    },
+    {
+      "id": "integration-codex",
+      "role": "integration",
+      "runtime": "codex",
+      "expectActive": false
+    }
+  ]
 }

package/skills/runtime-codex/SKILL.md

@@ -1,6 +1,57 @@
 # Codex Runtime
 
-- Treat the compiled task prompt as the authoritative assignment.
+<!-- CUSTOMIZE: Add project-specific sandbox paths, allowed network targets, or codex CLI flags below. -->
+
+## Core Rules
+
+- Treat the compiled task prompt as the authoritative assignment. It is the single source of scope and deliverables.
 - Keep terminal work concise and deterministic where possible.
 - Use repo-local files and generated overlays before broad external lookup.
 - Preserve required structured markers exactly in terminal output.
+- Do not assume interactive input is available. All commands must run non-interactively.
+
+## Tool Profile
+
+Codex sessions operate through terminal-only execution:
+
+- **Shell commands** -- your primary interface. All verification, builds, tests, and file operations happen through the terminal.
+- **`--add-dir` bundles** -- the orchestrator may provide additional directories as readable context. These appear as local paths in the sandbox.
+- **File I/O** -- read and write files through standard shell tools (cat, sed, tee, etc.).
+- **No interactive prompts** -- stdin is not connected. Commands requiring user input will hang or fail. Use flags like `-y`, `--non-interactive`, or `--batch` where available.
+- **No MCP servers** -- MCP tools are not available in Codex sessions.
+
+## Prompt Contract
+
+The compiled task prompt is the single authority for a Codex session:
+
+1. **Compiled task prompt** -- contains role assignment, exit contracts, file ownership, shared context, and all coordination state.
+2. **Added directories** -- supplementary context provided via `--add-dir`. Treat as read-only reference material.
+3. **Appended skill guidance** -- this file and any other resolved skills.
+
+All context is in the prompt and added directories. There is no system prompt layer beyond what Codex provides natively.
+
+## Output Format
+
+- Emit structured markers exactly as defined in wave-core. Place each marker on its own line in terminal output.
+- Use deterministic, reproducible commands. Prefer explicit paths and flags over relying on shell state.
+- When running verification commands, capture and report the exact output. Do not paraphrase.
+- Final output must include all required markers for your role before the session ends.
+
+## Sandbox Constraints
+
+- **Network** -- may be restricted or unavailable depending on Codex configuration. Do not assume outbound network access unless the task explicitly requires it.
+- **Repo-local preference** -- prefer files already in the repo or provided via `--add-dir` over fetching external resources.
+- **No persistent state** -- each session starts clean. Do not rely on artifacts from previous sessions unless they are committed to the repo.
+- **Filesystem scope** -- write only to paths within the workspace. The sandbox may reject writes outside the project root.
+- **External APIs** -- avoid calling external APIs unless the task explicitly requires live verification. If network is unavailable, record the gap as a proof limitation.
+
+<!-- CUSTOMIZE: List allowed network targets or external API endpoints for your project here. -->
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Allowed outbound network targets
+  - Project-specific --add-dir paths and their contents
+  - Custom sandbox filesystem restrictions
+  - Pre-installed tools available in the Codex sandbox
+-->

package/skills/runtime-codex/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "runtime-codex",
   "title": "Codex Runtime",
-  "description": "Codex-specific execution norms inside the Wave harness."
+  "description": "Configures Codex runtime behavior: terminal-only execution, compiled prompt contract, sandbox constraints, and deterministic output norms.",
+  "activation": {
+    "when": "Attach when the selected runtime is Codex so the agent follows terminal-first Codex execution constraints.",
+    "roles": [],
+    "runtimes": [
+      "codex"
+    ],
+    "deployKinds": []
+  },
+  "termination": "Stop when Codex-specific execution and output constraints have been applied for the current attempt.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "implementation-codex",
+      "role": "implementation",
+      "runtime": "codex",
+      "expectActive": true
+    },
+    {
+      "id": "implementation-claude",
+      "role": "implementation",
+      "runtime": "claude",
+      "expectActive": false
+    }
+  ]
 }

package/skills/runtime-local/SKILL.md

@@ -1,5 +1,44 @@
 # Local Runtime
 
+<!-- CUSTOMIZE: Add project-specific smoke validation targets, artifact paths, or local test commands below. -->
+
+## Core Rules
+
 - The local executor is a smoke surface, not a substitute for real external integrations.
 - Focus on prompt shape, file ownership, and artifact expectations.
 - Do not claim live deploy or external-environment proof from local smoke execution alone.
+- Treat local validation as a pre-flight check. It catches structural errors, not runtime correctness.
+
+## Scope Limitations
+
+The local runtime cannot prove certain categories of state:
+
+- **No live deploy proof** -- local execution cannot verify that a service is running in Railway, AWS, Kubernetes, or any remote environment.
+- **No external state proof** -- local execution cannot confirm database state, DNS propagation, certificate validity, or third-party API health.
+- **No real executor sessions** -- local smoke runs do not invoke Claude, Codex, or OpenCode. They validate the prompt and artifacts that would be sent to those runtimes.
+- **No network-dependent verification** -- health checks, endpoint tests, and webhook confirmations require a real runtime with network access.
+
+When a deliverable requires any of the above, record the gap explicitly. Do not approximate.
+
+## Smoke Validation Checklist
+
+When running a local smoke validation, verify each of the following:
+
+1. **Prompt structure** -- the compiled task prompt is valid, contains all required sections (role, exit contracts, file ownership, shared context), and is within size limits.
+2. **File ownership declarations** -- every file listed in ownership exists in the repo or has a clear creation expectation. No ownership conflicts between agents.
+3. **Deliverable paths** -- every exit contract deliverable references a concrete path or artifact. No dangling references.
+4. **Marker syntax** -- all marker templates in the prompt match the expected format from wave-core. Parsers will reject malformed markers.
+5. **Skill resolution** -- all skills referenced in the wave definition resolve to existing skill directories with valid `skill.json` and `SKILL.md` files.
+6. **Context bundle integrity** -- if overlays or context bundles are generated, they exist at the declared paths and are non-empty.
+7. **Role assignment consistency** -- each agent has exactly one role, and the role matches a known role skill.
+
+Report each check as pass, fail, or skip with a one-line reason.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific artifact paths to validate
+  - Additional structural checks for your wave definitions
+  - Custom prompt size limits
+  - Local test commands to run as part of smoke validation
+-->

package/skills/runtime-local/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "runtime-local",
   "title": "Local Runtime",
-  "description": "Local smoke-executor norms."
+  "description": "Configures local smoke-executor behavior: scope limitations, prompt shape validation, and smoke checklist for dry-run verification.",
+  "activation": {
+    "when": "Attach when the selected runtime is local smoke validation so the agent stays within local proof limits.",
+    "roles": [],
+    "runtimes": [
+      "local"
+    ],
+    "deployKinds": []
+  },
+  "termination": "Stop when local smoke validation boundaries and limitations are explicit for the current attempt.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "documentation-local",
+      "role": "documentation",
+      "runtime": "local",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-claude",
+      "role": "documentation",
+      "runtime": "claude",
+      "expectActive": false
+    }
+  ]
 }

package/skills/runtime-opencode/SKILL.md

@@ -1,6 +1,57 @@
 # OpenCode Runtime
 
+<!-- CUSTOMIZE: Add project-specific opencode.json settings, agent prompt conventions, or file overlay paths below. -->
+
+## Core Rules
+
 - Treat injected instructions and the selected agent prompt as authoritative.
 - Keep edits and summaries tightly scoped to the assigned files and closure target.
 - Prefer explicit repo files and generated overlays over ad hoc runtime assumptions.
 - Preserve Wave marker syntax exactly in output and logs.
+- Do not modify files outside your declared ownership without explicit coordination.
+
+## Tool Profile
+
+OpenCode sessions are edit-focused with the following capabilities:
+
+- **Agent prompt** -- the primary instruction set, configured in `opencode.json` or passed at invocation. Defines the agent's persona and constraints.
+- **`--file` flags** -- specific files provided to the session as editable context. These are your primary workspace.
+- **File reading** -- read project files to gather context for edits.
+- **File editing** -- apply targeted changes to owned files. Edits should be minimal and scoped.
+- **Shell execution** -- run commands for builds, tests, and verification within the project directory.
+- **No MCP servers** -- MCP tools are not available in OpenCode sessions.
+
+## Prompt Contract
+
+OpenCode sessions have a dual-authority prompt structure:
+
+1. **Agent prompt** -- the opencode agent configuration that defines behavioral rules and persona. Set in `opencode.json` or at invocation.
+2. **Injected instructions** -- the wave-orchestrator-compiled prompt containing role, exit contracts, file ownership, and shared context.
+3. **Appended skill guidance** -- this file and any other resolved skills.
+
+Both the agent prompt and injected instructions are authoritative. When they conflict on scope or deliverables, prefer the injected instructions (the compiled task prompt). When they conflict on behavioral rules, prefer the agent prompt.
+
+## Output Format
+
+- Emit structured markers exactly as defined in wave-core. Place each marker on its own line.
+- Only emit markers for your assigned role.
+- Keep edit descriptions concise. Name the file, the change, and the reason.
+- When reporting verification results, include the exact command and its output.
+- Preserve marker syntax in both terminal output and any log files generated.
+
+## Edit Discipline
+
+- Scope edits tightly to the assigned files listed in file ownership.
+- Prefer targeted replacements over full file rewrites.
+- When an edit depends on understanding adjacent code, read the relevant context first.
+- If a needed change falls outside your ownership, record it as a follow-up request naming the owning agent, the file, and the change.
+- Generated overlays (context bundles, summaries) are read-only reference. Do not edit overlay files.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific opencode.json agent configurations
+  - Additional --file paths commonly provided
+  - Edit scope restrictions for sensitive files
+  - Custom output format requirements
+-->

package/skills/runtime-opencode/skill.json

@@ -1,5 +1,36 @@
 {
   "id": "runtime-opencode",
   "title": "OpenCode Runtime",
-  "description": "OpenCode-specific execution norms inside the Wave harness."
+  "description": "Configures OpenCode runtime behavior: injected instructions, file attachment contract, edit-focused workflow, and marker preservation norms.",
+  "activation": {
+    "when": "Attach when the selected runtime is OpenCode so the agent follows file-attachment and edit-focused OpenCode conventions.",
+    "roles": [],
+    "runtimes": [
+      "opencode"
+    ],
+    "deployKinds": []
+  },
+  "termination": "Stop when OpenCode-specific attachment and editing rules have been applied for the current attempt.",
+  "permissions": {
+    "network": [],
+    "shell": [],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-opencode",
+      "role": "deploy",
+      "runtime": "opencode",
+      "expectActive": true
+    },
+    {
+      "id": "deploy-codex",
+      "role": "deploy",
+      "runtime": "codex",
+      "expectActive": false
+    }
+  ]
 }

package/skills/wave-core/SKILL.md

@@ -1,7 +1,114 @@
 # Wave Core
 
+<!-- CUSTOMIZE: Add project-specific coordination channels, artifact locations, or naming conventions below. -->
+
+## Core Rules
+
 - Re-read the compiled shared summary, inbox, and board projection before major decisions and before final output.
 - Treat file ownership, exit contracts, and structured markers as hard requirements.
 - Post coordination records for meaningful progress, blockers, decisions, and handoffs.
 - Make gaps explicit with exact files, exact fields, and exact follow-up owners.
 - Do not infer closure from intent alone. Closure requires proof artifacts and consistent shared state.
+- Silence is not evidence. If a deliverable is not mentioned in landed artifacts, it is not done.
+- When two sources conflict, prefer the one backed by landed code or durable proof over the one backed by prose.
+
+## Coordination Protocol
+
+1. Read the shared summary and your inbox at the start of every major step.
+2. Post a coordination record when any of these occur:
+   - meaningful progress on an exit contract deliverable
+   - a blocker is discovered or resolved
+   - a decision changes scope, ownership, or interface
+   - a handoff to another agent is needed
+   - a helper assignment is opened or resolved
+   - a clarification is routed or answered
+3. Each coordination record must include: agent id, timestamp context, topic, and actionable detail.
+4. Do not batch coordination. Post records as events occur so downstream agents see them promptly.
+5. When a record references another agent, name that agent explicitly.
+6. Coordination records are append-only. Do not edit or delete previous records; post corrections as new records.
+7. When you receive an inbox message that requires action, acknowledge it with a coordination record before proceeding.
+
+## Ownership & Boundaries
+
+- Only modify files you own. File ownership is declared in the wave definition under each agent.
+- If you need a change in a file you do not own, open a follow-up request naming the owning agent, the exact file, and the exact change needed.
+- Shared-plan docs (current-state.md, component matrix, roadmap) are owned by the documentation steward, not implementation agents.
+- Implementation-specific docs (inline comments, subsystem READMEs) stay with the implementation owner.
+- When ownership is ambiguous, post a coordination record requesting clarification before editing.
+- Helper assignments create temporary cross-boundary access. They remain blocking until the linked follow-up resolves.
+- Cross-lane dependencies require explicit dependency tickets. Do not assume another lane's state without a resolved ticket.
+
+## Proof Requirements
+
+- Every exit contract deliverable must have a corresponding proof artifact: a passing test, a generated file, a durable summary, or an explicit structured marker.
+- Generic claims ("tests pass", "works correctly") are not proof. Name the exact test file, command, or artifact.
+- Component promotions require evidence that the component actually reached the declared level, not just that adjacent code landed.
+- Runtime-facing proof must be real evidence (logs, health checks, build output), not future-work notes.
+- Proof must be durable. Transient output (terminal scrollback, ephemeral logs) is not proof unless captured into a file.
+- When proof cannot be produced within the wave, record the gap explicitly with the reason and the follow-up owner.
+
+## Closure Checklist
+
+A wave is closable only when all nine conditions are satisfied:
+
+1. **Exit contracts pass** -- every agent's declared exit contract deliverables are present and backed by proof artifacts.
+2. **Deliverables exist within ownership** -- each deliverable lives in files owned by the agent that produced it.
+3. **Component proof/promotions pass** -- promoted components reached their declared target level with evidence.
+4. **Helper assignments resolved** -- every helper assignment posted during the wave has a linked resolution.
+5. **Dependency tickets resolved** -- all inbound cross-lane dependency tickets are resolved or explicitly deferred.
+6. **Clarification follow-ups resolved** -- every routed clarification chain has a linked follow-up that is closed.
+7. **cont-EVAL satisfies targets** -- if the wave includes cont-EVAL, the eval marker shows `satisfied` with matching target and benchmark ids.
+8. **Integration recommends closure** -- the integration marker shows `ready-for-doc-closure` and is not contradicted by later evidence.
+9. **Documentation and cont-QA pass** -- doc closure marker is `closed` or `no-change`, and the cont-QA verdict is `PASS` with a matching gate marker.
+
+If any condition is not met, the wave remains open. Do not approximate closure.
+
+Closure runs in staged order:
+1. Implementation and proof (all implementation agents).
+2. cont-EVAL (if present) -- must report `satisfied` before integration runs.
+3. Integration -- must report `ready-for-doc-closure` before documentation and cont-QA run.
+4. Documentation -- must report `closed` or `no-change`.
+5. cont-QA -- final verdict. Only PASS allows the wave to close.
+
+Do not skip stages. Each stage depends on the prior stage completing.
+
+## Structured Markers Reference
+
+Emit markers exactly as shown. Parsers depend on the format.
+
+| Marker | Format |
+|---|---|
+| `[wave-gate]` | `[wave-gate] architecture=<pass\|concerns\|blocked> integration=<pass\|concerns\|blocked> durability=<pass\|concerns\|blocked> live=<pass\|concerns\|blocked> docs=<pass\|concerns\|blocked> detail=<text>` |
+| `[wave-eval]` | `[wave-eval] state=<satisfied\|needs-more-work\|blocked> targets=<n> benchmarks=<n> regressions=<n> target_ids=<csv> benchmark_ids=<csv> detail=<text>` |
+| `[wave-integration]` | `[wave-integration] state=<ready-for-doc-closure\|needs-more-work> claims=<n> conflicts=<n> blockers=<n> detail=<text>` |
+| `[wave-doc-closure]` | `[wave-doc-closure] state=<closed\|no-change\|delta> paths=<comma-separated-paths> detail=<text>` |
+| `[infra-status]` | `[infra-status] kind=<conformance\|role-drift\|dependency\|identity\|admission\|action> target=<surface> state=<checking\|setup-required\|setup-in-progress\|conformant\|drift\|blocked\|failed\|action-required\|action-approved\|action-complete> detail=<text>` |
+| `[deploy-status]` | `[deploy-status] state=<deploying\|healthy\|failed\|rolled-back> service=<name> detail=<text>` |
+
+- Every marker must appear on a single line.
+- The `detail` field is free text but should be concise (under 120 characters).
+- Only the role that owns the marker type should emit it. Do not emit markers for other roles.
+
+Marker ownership:
+
+| Marker | Emitted by |
+|---|---|
+| `[wave-gate]` | cont-QA role |
+| `[wave-eval]` | cont-EVAL role |
+| `[wave-integration]` | Integration role |
+| `[wave-doc-closure]` | Documentation role |
+| `[infra-status]` | Infra role |
+| `[deploy-status]` | Deploy role |
+
+When you encounter a marker in the coordination log, treat it as the authoritative state from that role. If a role emits multiple markers during a wave, the last one supersedes earlier ones.
+
+<!-- CUSTOMIZE: Add project-specific marker types or extend existing formats here. -->
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Project-specific coordination record format
+  - Additional closure conditions beyond the nine listed
+  - Custom marker types for project-specific workflows
+  - Ownership rules for monorepo sub-packages
+-->