@chllming/wave-orchestration 0.5.2 → 0.5.4

package/docs/README.md

@@ -0,0 +1,39 @@
+# Wave Documentation
+
+This repository now uses a layered docs structure so operators, maintainers, and adopting repos can find the right level of detail quickly.
+
+## Suggested Structure
+
+- `docs/concepts/`
+  Mental models and architecture. Read these first if you want to understand what a wave is, how runtime-agnostic execution works, or how Context7 differs from skills.
+- `docs/guides/`
+  Task-oriented workflows. Use these when you need to set up the planner, choose an operating mode, or decide how to run tmux and terminal surfaces.
+- `docs/reference/`
+  Exact command, config, and file-format details. Use this when you need precise key names, runtime options, or bundle structure.
+- `docs/plans/`
+  Starter plan docs, runbooks, roadmap, and current-state pages that ship with the package and seed adopting repositories.
+- `docs/research/`
+  Source index for the external papers and articles that informed the harness design. Hydrated caches stay local and ignored.
+
+## Start Here
+
+- New to Wave:
+  Read [concepts/what-is-a-wave.md](./concepts/what-is-a-wave.md), [concepts/runtime-agnostic-orchestration.md](./concepts/runtime-agnostic-orchestration.md), and [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md).
+- Drafting or revising waves:
+  Read [guides/planner.md](./guides/planner.md) and then the operator runbook in [plans/wave-orchestrator.md](./plans/wave-orchestrator.md).
+- Running live waves:
+  Read [guides/terminal-surfaces.md](./guides/terminal-surfaces.md), [concepts/operating-modes.md](./concepts/operating-modes.md), and [plans/wave-orchestrator.md](./plans/wave-orchestrator.md).
+- Tuning runtime behavior:
+  Read [reference/runtime-config/README.md](./reference/runtime-config/README.md) and [reference/skills.md](./reference/skills.md).
+
+## Package vs Repo-Owned Material
+
+- Package-owned generic runtime docs live here under `docs/`.
+- Repo-specific policy should stay in:
+  - `wave.config.json`
+  - `docs/agents/*.md`
+  - `skills/`
+  - `docs/plans/waves/`
+  - the repository source itself
+
+That split keeps the engine generic while letting each adopting repository own its actual operating rules.

package/docs/concepts/context7-vs-skills.md

@@ -0,0 +1,94 @@
+# Context7 vs Skills
+
+Context7 and skills solve different problems.
+
+Use Context7 for external library truth. Use skills for repo-owned, reusable operating knowledge.
+
+## Short Version
+
+- Context7
+  Up-to-date third-party library or API context.
+- Skills
+  Reusable guidance tailored to your repository, environments, roles, and runtime choices.
+
+## Comparison
+
+| Surface | Context7 | Skills |
+| --- | --- | --- |
+| Primary purpose | External docs and SDK truth | Internal reusable operating guidance |
+| Typical source | `docs/context7/bundles.json` and fetched snippets | `skills/<skill-id>/skill.json` and `SKILL.md` |
+| Ownership | Package or repo operator config | Repository maintainers |
+| Scope | Library versions, APIs, setup syntax | Coding rules, deploy norms, repo conventions, workflow rules |
+| Selection | Wave defaults plus per-agent `### Context7` | Base plus role, runtime, deploy-kind, and per-agent `### Skills` |
+| Change rate | Often changes with external libraries | Changes when your repo or environment changes |
+| Projection | Injected as prompt context | Projected into runtime-specific overlays and prompt context |
+
+## When To Use Context7
+
+Use Context7 when the agent needs information that lives outside the repo and can change over time, such as:
+
+- framework APIs
+- SDK method signatures
+- library setup syntax
+- version-specific behavior
+- hosted service docs
+
+Context7 is intentionally narrow. It is for third-party truth, not for your repo's own architecture or policies.
+
+## When To Use Skills
+
+Use skills when the guidance is reusable, repo-owned, and should survive across waves, roles, or runtimes, such as:
+
+- coding norms
+- review expectations
+- environment-specific rules
+- Railway, Kubernetes, or GitHub release procedures
+- runtime-specific instructions for Codex, Claude, or OpenCode
+- role-oriented heuristics for implementation, deploy, evaluator, or research agents
+
+## What Remains Authoritative
+
+Neither Context7 nor skills replace the actual repo.
+
+The highest-authority sources are still:
+
+- repository source
+- `wave.config.json`
+- wave markdown
+- role prompts in `docs/agents/*.md`
+- shared plan docs
+- the generated shared summary and inboxes for the active run
+
+Skills are additive guidance. Context7 is non-canonical external context. The repo and wave artifacts remain authoritative.
+
+## How They Work Together
+
+A typical deploy-focused wave might use both:
+
+- Context7
+  For the latest official framework or platform docs.
+- Skills
+  For repo-specific deploy rules, Railway conventions, and runtime-specific execution guidance.
+
+That combination keeps the agent grounded in both external truth and local operating rules.
+
+## Runtime Behavior
+
+Both surfaces are runtime aware, but in different ways:
+
+- Context7 is fetched and injected into the compiled prompt.
+- Skills are resolved after executor selection and then projected into the runtime-specific overlay surface for that executor.
+
+Because of that:
+
+- changing Context7 selection changes the prompt fingerprint
+- changing resolved skills also changes the prompt fingerprint and trace metadata
+
+## Best Practice
+
+- Put version-sensitive third-party docs into Context7.
+- Put stable repo or environment playbooks into skills.
+- Keep wave prompts focused on the specific assignment, not long-lived reusable rules.
+- If the same guidance is repeated across waves, promote it into a skill.
+
+For exact skill bundle layout and resolution order, see [reference/skills.md](../reference/skills.md).

package/docs/concepts/operating-modes.md

@@ -0,0 +1,91 @@
+# Oversight, Dark-Factory, And Human Feedback
+
+Wave now has an explicit planning vocabulary for execution posture.
+
+Today that posture is captured in project profile memory and planner output. The deeper runtime policy attached to those modes is still roadmap work, so this page distinguishes what is already shipped from what is still a convention.
+
+## The Two Postures
+
+- `oversight`
+  Human review and intervention are expected parts of the operating model for risky work.
+- `dark-factory`
+  The goal is end-to-end execution without routine human intervention.
+
+These values are stored in `.wave/project-profile.json` and emitted into planner-generated specs and wave markdown.
+
+## What Ships Today
+
+Today the runtime ships:
+
+- project-profile memory for default oversight mode
+- planner prompts that ask for oversight mode
+- generated specs and waves that record the chosen mode
+- deploy-environment memory that helps infra and release planning
+- orchestrator-first clarification handling and human feedback queueing
+
+The runtime does not yet enforce a separate hard policy profile for `dark-factory` beyond what is already encoded in the wave itself.
+
+## How To Interpret The Modes Right Now
+
+Treat them as planning posture:
+
+- `oversight`
+  Default when a human operator should expect to inspect progress, answer questions, or approve risky transitions.
+- `dark-factory`
+  Use only when the wave already has explicit environment modeling, validation, rollback posture, and clear closure signals.
+
+## Human Feedback Is Not The Same Thing
+
+Human feedback is a runtime escalation mechanism, not an operating mode.
+
+The launcher flow is:
+
+1. agent emits a clarification request or blocker
+2. the orchestrator tries to resolve it from repo state, policy, ownership, or targeted rerouting
+3. only unresolved items become human feedback tickets
+4. those tickets stay visible in ledgers, summaries, and traces until resolved
+
+That means even `oversight` mode still tries to keep routine clarification inside the orchestration loop before escalating to a human.
+
+## Oversight Mode Best Fit
+
+Choose `oversight` when:
+
+- deploy or infra mutation is live and risky
+- the environment model is incomplete
+- rollback steps are still implicit
+- legal, compliance, or release decisions need explicit human sign-off
+- the repo is still shaping its skills and closure rules
+
+## Dark-Factory Best Fit
+
+Choose `dark-factory` only when all of these are already true:
+
+- deploy environments are typed and explicit
+- runtime and credential expectations are known
+- validation commands are concrete
+- rollback or recovery posture is documented
+- closure evidence is machine-checkable or strongly operator-visible
+- missing context would be treated as a planning failure, not something to improvise live
+
+## Best Practice
+
+Default to `oversight` until the repo has earned `dark-factory`.
+
+That usually means:
+
+- stable skills for deploy and infra work
+- consistent deploy-environment naming
+- strong validation commands
+- reliable docs and trace review habits
+- low ambiguity about who owns live mutation
+
+## Relationship To The Roadmap
+
+The roadmap still includes stronger explicit oversight vs dark-factory workflows. What is shipped today is the planning foundation:
+
+- stored project defaults
+- typed values in planner output
+- better environment modeling
+
+The stricter execution semantics are the next step, not a hidden already-finished feature.

package/docs/concepts/runtime-agnostic-orchestration.md

@@ -0,0 +1,95 @@
+# Runtime-Agnostic Orchestration
+
+Wave is runtime agnostic at the orchestration layer.
+
+That means planning, coordination, closure, and traces do not depend on whether the selected executor is Codex, Claude Code, OpenCode, or the local smoke executor.
+
+## What Stays The Same Across Runtimes
+
+These layers are runtime-neutral:
+
+- wave parsing and validation
+- component and closure gates
+- compiled shared summaries and per-agent inboxes
+- coordination log and rendered message board
+- helper assignments and dependency handling
+- integration summaries, docs queues, and ledgers
+- dry-run previews
+- trace bundles and replay metadata
+
+The runtime only changes at the last step, when the launcher translates the resolved assignment into an executor-specific invocation.
+
+## Where Runtime-Specific Logic Lives
+
+Runtime-specific behavior is isolated to the executor adapter layer:
+
+- Codex
+  `codex exec` invocation, sandbox flags, `--add-dir`, JSON mode, search, images, and other `exec` flags.
+- Claude
+  `claude -p` plus system-prompt overlay, settings merge, hooks, and permission surface.
+- OpenCode
+  `opencode run` plus generated `opencode.json`, attached files, and runtime instruction overlays.
+- Local
+  A smoke executor used for prompt and closure verification without a real hosted runtime.
+
+The orchestration substrate above those adapters does not need to know how the runtime transports prompts.
+
+## Why This Matters
+
+Runtime agnosticism gives you:
+
+- the same plan and closure model across vendors
+- replay and audit surfaces that do not care which runtime produced the work
+- per-role runtime choice without rewriting authoring conventions
+- retry-time fallback without inventing a second planning model
+
+## Runtime Resolution
+
+Executor choice resolves in a fixed order:
+
+1. explicit agent `### Executor` id
+2. executor profile id
+3. lane role default
+4. CLI `--executor`
+5. global default
+
+After that choice is final, the launcher resolves runtime-specific overlays and any runtime-attached skill packs.
+
+## Fallback And Mix Policy
+
+Wave is not runtime blind. It is runtime agnostic, but still runtime aware.
+
+- runtime mix targets can cap how many agents use a given executor
+- executor profiles can declare fallbacks
+- lane policy can supply default executor choices by role
+- retries can reassign an agent to a policy-safe fallback runtime
+
+The important part is that fallback does not change the higher-level wave contract. The runtime changes, but the ownership, closure, and trace model remain the same.
+
+## Skills Across Runtimes
+
+The skill system follows the same pattern:
+
+- `skills/` is the canonical repo-owned source
+- the launcher resolves skill ids without caring which runtime will consume them
+- the executor adapter projects those skills into the surface each runtime understands
+
+Examples:
+
+- Codex receives skill bundle directories through `--add-dir`
+- Claude receives merged skill text through the generated system prompt overlay
+- OpenCode receives skill instructions and attached files through `opencode.json` and `--file`
+- Local receives prompt-only projections
+
+The bundle is shared. The projection is runtime specific.
+
+## Best Practice
+
+Keep planning, ownership, and proof requirements runtime neutral whenever possible. Use runtime-specific settings only for:
+
+- transport details
+- model or budget selection
+- safety and permission settings
+- runtime-native adapter instructions
+
+That separation is what keeps the orchestrator portable instead of turning it into a Codex-only or Claude-only harness.

package/docs/concepts/what-is-a-wave.md

@@ -0,0 +1,133 @@
+# What Is A Wave?
+
+A wave is the main planning and execution unit in Wave Orchestration.
+
+It is not just a prompt file. A wave is a bounded slice of repository work with:
+
+- explicit scope
+- named owners
+- runtime and context requirements
+- proof and closure rules
+- durable coordination state
+- replayable execution artifacts
+
+## Core Terms
+
+- Lane
+  An ordered sequence of waves. The default lane in this repo is `main`.
+- Wave
+  One numbered work package inside a lane, usually stored as `docs/plans/waves/wave-<n>.md`.
+- Agent
+  One role inside the wave, such as implementation, integration, documentation, evaluator, infra, or deploy.
+- Attempt
+  One execution pass of a wave. A wave can have multiple attempts due to retries or fallback.
+- Closure
+  The final proof pass that decides whether the wave is actually done, not just partially implemented.
+
+## Why Waves Exist
+
+Waves force a higher planning bar than ad hoc prompts. A good wave answers:
+
+- What is changing now, and why now?
+- Which components or docs are in scope?
+- Which agent owns each slice?
+- What evidence closes the wave?
+- Which dependencies, helper requests, or escalations can still block completion?
+
+## Wave Anatomy
+
+Wave markdown is the authored execution surface today. A typical wave can include:
+
+- title and commit message
+- project profile details such as oversight mode and lane
+- sequencing note
+- reference rule
+- deploy environments
+- component promotions
+- Context7 defaults
+- one `## Agent ...` block per role
+
+Inside each agent block, the important sections are:
+
+- `### Role prompts`
+  Standing role identity imported from `docs/agents/*.md`.
+- `### Executor`
+  Runtime selection, profile, model, fallbacks, and budgets.
+- `### Context7`
+  External library truth to prefetch and inject.
+- `### Skills`
+  Reusable repo-owned environment or workflow guidance resolved after runtime selection.
+- `### Components`
+  The components that agent is responsible for proving or promoting.
+- `### Capabilities`
+  Optional routing hints for follow-up work.
+- `### Deliverables`
+  Exact repo-relative outputs that must exist before closure can pass.
+- `### Prompt`
+  The specific task, file ownership, requirements, and validation instructions.
+- `### Exit contract`
+  The completion, durability, proof, and documentation expectations that gate closure.
+
+## Standard Roles
+
+The starter runtime expects three closure roles:
+
+- `A8`
+  Integration steward
+- `A9`
+  Documentation steward
+- `A0`
+  Evaluator
+
+Implementation or specialist agents own the actual work slices. Closure roles do not replace implementation ownership; they decide whether the combined result is closure-ready.
+
+## Lifecycle Of A Wave
+
+1. Author or draft the wave.
+2. Run `wave launch --dry-run --no-dashboard`.
+3. The launcher validates the wave, resolves executors and skills, builds prompts, and materializes operator surfaces.
+4. A live run launches implementation agents first when implementation work remains.
+5. Agents write structured coordination events instead of relying on ad hoc terminal output.
+6. The launcher checks implementation contracts, promoted-component proof, helper assignments, dependencies, and clarification state.
+7. If implementation is ready, closure runs in order: integration, documentation, evaluator.
+8. The attempt is captured in per-wave traces, ledgers, inboxes, summaries, and copied artifacts.
+
+## What Makes A Wave "Done"
+
+A wave is not done because an agent said so. It is done only when the runtime surfaces agree:
+
+- implementation exit contracts pass
+- required deliverables exist and stay within ownership boundaries
+- required component proof and promotions pass
+- helper assignments are resolved
+- required dependency tickets are resolved
+- clarification follow-ups or escalations are resolved
+- integration recommends closure
+- documentation and evaluator closure pass
+
+## Where The State Lives
+
+The wave file is only part of the story. The runtime writes durable state under `.tmp/<lane>-wave-launcher/`, including:
+
+- prompts and logs
+- status summaries
+- coordination logs
+- rendered message boards
+- compiled inboxes
+- ledger and docs queue
+- integration summaries
+- dependency snapshots
+- executor overlays
+- trace bundles
+
+That is why a wave is better understood as a bounded execution record, not just a markdown file.
+
+## Planner Specs vs Markdown
+
+The planner foundation adds a JSON draft spec at `docs/plans/waves/specs/wave-<n>.json`.
+
+- The JSON spec is the canonical planner artifact.
+- The rendered markdown stays compatible with the launcher and parser.
+- The launcher still executes the markdown wave file today.
+
+This split keeps authoring structured while preserving the established execution surface.

package/docs/guides/planner.md

@@ -0,0 +1,113 @@
+# Planner Guide
+
+The planner foundation is the first structured authoring layer on top of the existing wave runtime.
+
+It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
+
+## What Ships Today
+
+- `wave project setup`
+- `wave project show`
+- `wave draft`
+- persistent project memory in `.wave/project-profile.json`
+- JSON specs in `docs/plans/waves/specs/wave-<n>.json`
+- rendered markdown waves in `docs/plans/waves/wave-<n>.md`
+- component matrix updates for promoted components
+
+## What The Planner Does Not Yet Ship
+
+- ad hoc transient runs
+- forward replanning of later waves
+- separate runtime enforcement for oversight vs dark-factory
+
+Those remain roadmap work. The planner foundation is about better structured authoring, not a second execution engine.
+
+## Project Profile
+
+Run:
+
+```bash
+pnpm exec wave project setup
+pnpm exec wave project show --json
+```
+
+The saved profile remembers:
+
+- whether the repo is a new project
+- default oversight mode
+- default terminal surface for live runs (`vscode` or `tmux`; `none` remains dry-run only)
+- default draft template
+- default lane
+- typed deploy environments
+
+This lets later drafts inherit repo-specific defaults instead of asking the same bootstrap questions every time.
+
+## Drafting A Wave
+
+Run:
+
+```bash
+pnpm exec wave draft --wave 1 --template implementation
+```
+
+Supported templates today:
+
+- `implementation`
+- `qa`
+- `infra`
+- `release`
+
+The planner writes:
+
+- `docs/plans/waves/specs/wave-<n>.json`
+- `docs/plans/waves/wave-<n>.md`
+
+The JSON spec is the canonical planner artifact. The markdown wave remains the launcher-compatible execution surface.
+
+## What The Planner Asks For
+
+The draft flow asks for structured inputs such as:
+
+- wave title and commit message
+- sequencing notes and reference rules
+- oversight mode
+- deploy environments in scope
+- component promotions and target levels
+- worker count and worker roles
+- executor profiles
+- file ownership
+- Context7 defaults and per-agent bundles
+- validation commands
+- exit contracts
+
+That gives you a wave that is much closer to launch-ready than a blank markdown template.
+
+## Planner And Skills
+
+The planner does not auto-discover every possible skill bundle yet, but it supports explicit per-agent `### Skills` in the rendered output.
+
+The more important interaction is indirect:
+
+- project profile remembers deploy environments
+- planner-generated waves carry `## Deploy environments`
+- deploy-kind skill attachment uses the wave's default deploy environment kind
+
+So planner structure and skill resolution already reinforce each other.
+
+## Recommended Workflow
+
+1. Run `pnpm exec wave project setup` once for the repo.
+2. Use `pnpm exec wave draft --wave <n> --template <template>`.
+3. Review the generated JSON spec and markdown wave.
+4. Adjust repo-specific prompts, file ownership, skills, and validation commands.
+5. Run `pnpm exec wave launch --lane <lane> --start-wave <n> --end-wave <n> --dry-run --no-dashboard`.
+6. Only launch live once the dry-run artifacts look correct.
+
+## Best Practices
+
+- Treat the generated draft as a strong starting point, not untouchable output.
+- Tighten validation commands before launch.
+- Keep file ownership narrow and explicit.
+- Add explicit `### Skills` only when the lane, role, runtime, and deploy-kind defaults are not enough.
+- Use the component matrix as a planning contract, not just a reporting surface.
+- Prefer updating the project profile when the same answers recur across waves.

package/docs/guides/terminal-surfaces.md

@@ -0,0 +1,80 @@
+# Terminal Surfaces And Dashboards
+
+Wave has separate concepts for execution substrate and operator surface.
+
+The important detail is:
+
+- live runs use `tmux` sessions
+- terminal surfaces control how operators attach to those sessions
+
+## The Three Terminal Surfaces
+
+- `vscode`
+  The launcher writes temporary entries to `.vscode/terminals.json` so VS Code can attach to the tmux sessions.
+- `tmux`
+  The launcher uses tmux only and never touches `.vscode/terminals.json`.
+- `none`
+  Dry-run only. No live terminal surface is allowed in this mode.
+
+## What `vscode` Really Means
+
+`vscode` is not a second process host. It is a convenience attachment surface.
+
+The actual live sessions still run in tmux. The VS Code terminal registry just exposes stable attach commands for those tmux sessions.
+
+Use `vscode` when:
+
+- your main operator flow is inside VS Code
+- you want one-click attach behavior for agent sessions and dashboards
+- touching `.vscode/terminals.json` is acceptable in the repo
+
+## What `tmux` Really Means
+
+`tmux` is the cleanest fully terminal-native operator surface.
+
+Use `tmux` when:
+
+- you are on a remote shell or devbox
+- you want zero VS Code coupling
+- you want a headless or low-friction terminal operator workflow
+- the repo should never be mutated with temporary VS Code terminal entries
+
+## Dashboard Behavior
+
+By default the launcher can start per-wave dashboard sessions in tmux.
+
+Important flags:
+
+- `--no-dashboard`
+  Disable the per-wave tmux dashboard session.
+- `--cleanup-sessions`
+  Kill lane tmux sessions after each wave. This is the default.
+- `--keep-sessions`
+  Preserve tmux sessions after the wave for inspection.
+- `--keep-terminals`
+  Keep temporary VS Code terminal entries instead of cleaning them up.
+
+## Best Practices
+
+- Use `vscode` for local interactive operator work when the temporary terminal registry is useful.
+- Use `tmux` for remote, CI-like, or editor-independent operation.
+- Use `none` only with `--dry-run`.
+- Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
+- Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.
+
+## Suggested Defaults
+
+- Local development:
+  `vscode`
+- Remote shell or devbox:
+  `tmux`
+- CI validation:
+  `none` with `--dry-run`
+
+## Example Commands
+
+```bash
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface vscode
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --terminal-surface tmux --keep-sessions
+pnpm exec wave launch --lane main --start-wave 2 --end-wave 2 --dry-run --no-dashboard --terminal-surface none
+```

package/docs/plans/context7-wave-orchestrator.md

@@ -1,5 +1,7 @@
 # Context7 and Wave Orchestrator
 
+See also [concepts/context7-vs-skills.md](../concepts/context7-vs-skills.md) for how Context7 differs from the repo-owned skill system.
+
 Context7 is for external library truth. Repository docs and source are for repository truth.
 
 ## Rules

package/docs/plans/current-state.md

@@ -4,7 +4,16 @@
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
 - The default lane is `main`.
+- Planner foundation is now shipped:
+  - `.wave/project-profile.json` stores default oversight mode, terminal surface, draft template, lane, and deploy-environment memory
+  - `wave project setup|show` manage that profile
+  - `wave draft` writes planner JSON specs plus launcher-compatible markdown waves
 - The harness supports `codex`, `claude`, `opencode`, and `local` executors.
+- Cross-runtime skills are now first-class:
+  - canonical bundles live under `skills/`
+  - lane config can attach skills by base, role, runtime, and deploy kind
+  - wave agents can add explicit `### Skills`
+  - runtime projections are generated for Codex, Claude, OpenCode, and local execution
 - The runtime now includes:
   - a canonical coordination JSONL log
   - a generated markdown board projection
@@ -20,6 +29,7 @@
   - Claude settings overlay merging for inline settings and hooks
   - OpenCode merged config overlays plus multi-file attachments
   - dry-run prompt and executor-preview materialization under `.tmp/<lane>-wave-launcher/dry-run/`
+  - operator-selectable terminal surfaces: `vscode`, `tmux`, or `none` for dry-run only
 - Full runtime configuration reference pages now ship under `docs/reference/runtime-config/`.
 - Lane runtime policy is active through `wave.config.json`:
   - role-based default executors