@open-agent-toolkit/cli 0.1.33 → 0.1.35

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -103,6 +103,26 @@ oat config set workflow.autoArtifactReview.analysis false --local
 
 When archive settings are configured, completion uploads dated archive snapshots to S3, exports dated summary snapshots into the configured summary reference directory, and lets `oat-wrap-up` write tracked wrap-up reports into the configured wrap-up directory.
 
+## `oat gate ...`
+
+Use `oat gate` when a gate-aware skill should run a configured final command
+before it is considered done.
+
+Available commands:
+
+- `oat gate resolve <skill>` - inspect the resolved gate config for one skill
+- `oat gate set <skill>` / `oat gate unset <skill>` - write or clear a skill gate
+- `oat gate target set <id>` / `oat gate target unset <id>` - write or clear an exec target
+- `oat gate cross-provider-exec <prompt...>` - select an available exec target and run the prompt there
+
+The most common command is `oat gate cross-provider-exec`, which avoids the
+current runtime by default so a review gate can run in a fresh Codex, Claude, or
+Cursor runtime. Target commands are stored as JSON argv arrays, so configure
+them with `oat gate target set --base-command-json ...` rather than
+`oat config set`.
+
+For schema, examples, and current V1 limits, see [Workflow Gates](workflow-gates.md).
+
 Use these reference pages for file ownership and schema details:
 
 - [File Locations](../reference/file-locations.md)

package/assets/docs/cli-utilities/configuration.md

@@ -18,12 +18,12 @@ For the deep file-by-file reference, see:
 
 ## The four config surfaces
 
-| Surface              | File                     | Typical contents                                                                                                        | Primary CLI surface                        |
-| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| Shared repo config   | `.oat/config.json`       | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, and `tools.*` | `oat config get/set/list/describe`         |
-| Repo-local config    | `.oat/config.local.json` | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, and repo-local `activeIdea`        | `oat config get/set/list/describe`         |
-| User config          | `~/.oat/config.json`     | User-level state such as global `activeIdea` fallback                                                                   | `oat config describe`                      |
-| Provider sync config | `.oat/sync/config.json`  | Provider enablement and sync strategy settings                                                                          | `oat providers set`, `oat config describe` |
+| Surface              | File                     | Typical contents                                                                                                                                      | Primary CLI surface                            |
+| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Shared repo config   | `.oat/config.json`       | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/list/describe`, `oat gate` |
+| Repo-local config    | `.oat/config.local.json` | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/list/describe`, `oat gate` |
+| User config          | `~/.oat/config.json`     | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config describe`, `oat gate`              |
+| Provider sync config | `.oat/sync/config.json`  | Provider enablement and sync strategy settings                                                                                                        | `oat providers set`, `oat config describe`     |
 
 The main split is:
 
@@ -86,6 +86,7 @@ Common keys in `.oat/config.json`:
 - `archive.awsProfile` — optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
 - `tools.<pack>` — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation
+- `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
 
 Tool-pack state example:
 
@@ -96,6 +97,10 @@ oat config set tools.project-management true
 
 The `tools.*` keys are primarily maintained by `oat tools install`, `oat tools update`, and `oat tools remove`, but they are intentionally visible through `oat config` so workflows and operators can inspect or override pack-state signals when needed.
 
+Workflow gate objects are structured config and use their own command group
+instead of the scalar `oat config set` surface. See
+[Workflow Gates](workflow-gates.md) for the full command surface and examples.
+
 Archive example:
 
 ```bash
@@ -150,6 +155,11 @@ Use `~/.oat/config.json` for user fallback state when no repo-local value is set
 
 - `activeIdea`
 
+Repo-local and user config can also hold workflow defaults, including
+`workflow.gates.*`. This is useful for personal runtime availability: for
+example, one user may prefer `claude -p` as a gate target while another prefers
+`codex exec`.
+
 In practice, you usually inspect these via:
 
 ```bash
@@ -260,6 +270,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
 - `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
 - `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
+- `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 
 ### Auto artifact-review preferences
 

package/assets/docs/cli-utilities/index.md

@@ -15,6 +15,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
+- [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch with `oat gate`.
 
 ## What Lives Here
 
@@ -25,6 +26,7 @@ Examples include:
 - bootstrap and setup flows such as `oat init`
 - bundled pack management through `oat tools`
 - general configuration guidance
+- workflow gate commands for per-skill final checks and cross-runtime review dispatch
 - utility command groups for config, local state, diagnostics, and related inspection flows
 
 ## Who It's For
@@ -47,6 +49,7 @@ Use CLI Utilities when:
 - Use [CLI Bootstrap](bootstrap.md) when you are starting with `oat init`.
 - Go to [Tool Packs](tool-packs.md) when you are managing bundled OAT packs and installed assets.
 - Read [Configuration](configuration.md) for config semantics, or [Config and Local State](config-and-local-state.md) for inspection and diagnostic command groups.
+- Use [Workflow Gates](workflow-gates.md) when you want a skill to run a configured final command before it is considered done.
 
 ## Common Tasks
 
@@ -54,6 +57,7 @@ Use CLI Utilities when:
 - Manage installed packs in [Tool Packs](tool-packs.md).
 - Adjust settings in [Configuration](configuration.md).
 - Use [Config and Local State](config-and-local-state.md) for the utility command groups that support inspection and diagnostics.
+- Configure cross-runtime review gates in [Workflow Gates](workflow-gates.md).
 
 ## Go Deeper
 
@@ -61,3 +65,4 @@ Use CLI Utilities when:
 - [Tool Packs](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
+- [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch.

package/assets/docs/cli-utilities/tool-packs.md

@@ -171,7 +171,7 @@ The `core` pack contains foundational diagnostic and documentation skills:
 
 Key behavior:
 
-- Core pack always installs at **user scope** (`~/.agents/skills/`), regardless of the `--scope` flag. This ensures core skills are available in any directory.
+- Core pack always installs at **user scope** (`~/.agents/skills/`). It does not honor a different scope, and passing a conflicting explicit `--scope` (e.g. `oat init tools core --scope project`) is rejected with an error rather than silently ignored; omit `--scope` or pass `--scope user`. This ensures core skills are available in any directory.
 - Core is checked by default in the `oat init tools` guided setup.
 - Installation also bundles OAT documentation to `~/.oat/docs/` for the oat-docs skill.
 - `oat tools update --pack core` refreshes both skills and `~/.oat/docs/` documentation.

package/assets/docs/cli-utilities/workflow-gates.md

@@ -0,0 +1,163 @@
+---
+title: Workflow Gates
+description: Configure per-skill final commands and cross-runtime review dispatch with oat gate.
+---
+
+# Workflow Gates
+
+Workflow gates let a gate-aware skill run a configured final command before it
+is considered done. The common use is independent review: one runtime performs
+the work, then `oat gate cross-provider-exec` dispatches a prompt to another
+runtime such as Codex or Claude.
+
+V1 gates are deliberately thin. A gate command passes or fails by exit code, and
+the skill owns what to do next.
+
+## Gate config
+
+Gate config lives under `workflow.gates.skills` and is keyed by skill name.
+
+```json
+{
+  "workflow": {
+    "gates": {
+      "skills": {
+        "oat-project-implement": {
+          "command": "oat gate cross-provider-exec \"Use oat-project-review-provide to review the current project\"",
+          "description": "Run a fresh-runtime final review before implementation is considered done.",
+          "onFailure": "block",
+          "maxAttempts": 2
+        }
+      }
+    }
+  }
+}
+```
+
+Fields:
+
+- `command` - shell command the skill runs in its Gate Execution step.
+- `onFailure` - `block`, `prompt`, or `warn`.
+- `description` - optional context for the agent running the gate.
+- `maxAttempts` - retry bound for `block`; defaults to `2`.
+
+`oat-project-plan` and `oat-project-implement` are currently gate-aware. Gate
+awareness is declared in skill frontmatter with `oat_gateable: true`, and
+`oat internal validate-oat-skills` warns when config targets a missing or
+non-gateable skill.
+
+## Exec targets
+
+`oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.
+Targets are keyed by opaque id. OAT uses only the declared runtime, commands,
+and priority; it does not parse model names or infer provider semantics from the
+id.
+
+Built-in targets:
+
+| Target id        | Runtime  | Base command                        | Current-host detector                   |
+| ---------------- | -------- | ----------------------------------- | --------------------------------------- |
+| `codex-default`  | `codex`  | `["codex", "exec"]`                 | `CODEX_THREAD_ID` or `CODEX_SESSION_ID` |
+| `claude-default` | `claude` | `["claude", "-p"]`                  | `CLAUDECODE`                            |
+| `cursor-default` | `cursor` | `["cursor-agent", "-p", "--force"]` | `CURSOR_AGENT`                          |
+
+Config layers can partially override a target or disable it with `null`. Use the
+dedicated target writer instead of `oat config set` because target commands are
+structured argv arrays:
+
+```bash
+oat gate target set claude-opus \
+  --runtime claude \
+  --base-command-json '["claude","-p","--model","opus"]' \
+  --availability-json '["claude","--version"]' \
+  --priority 90 \
+  --user
+```
+
+JSON argv is intentional: provider commands often contain flags such as `-p` or
+`--model`, which would be ambiguous as variadic CLI options.
+
+## Command surface
+
+Inspect a skill gate:
+
+```bash
+oat gate resolve oat-project-implement --json
+```
+
+Set or clear a skill gate:
+
+```bash
+oat gate set oat-project-implement \
+  --command 'oat gate cross-provider-exec "Use oat-project-review-provide to review the current project"' \
+  --description "Run final review in another runtime" \
+  --on-failure block \
+  --max-attempts 2 \
+  --user
+
+oat gate unset oat-project-implement --user
+```
+
+Set or clear an exec target:
+
+```bash
+oat gate target set codex-high \
+  --runtime codex \
+  --base-command-json '["codex","exec","--model","gpt-5.5"]' \
+  --availability-json '["codex","--version"]' \
+  --priority 90 \
+  --user
+
+oat gate target unset codex-high --user
+```
+
+Dispatch a prompt through the target registry:
+
+```bash
+oat gate cross-provider-exec "Use oat-project-review-provide to review the current project"
+```
+
+By default the dispatcher:
+
+1. Resolves built-in and configured exec targets.
+2. Detects the current runtime with host detection commands.
+3. Applies `--avoid same-runtime`.
+4. Checks candidate availability in descending priority order, with target id as
+   the tie-breaker.
+5. Runs the chosen `baseCommand` with the prompt appended.
+6. Exits with the child process status.
+
+Use `--target <id>` to pin one target and skip detection/avoidance:
+
+```bash
+oat gate cross-provider-exec --target claude-opus "Review the current project"
+```
+
+Use `--avoid none` only when you intentionally allow the current runtime to be
+selected:
+
+```bash
+oat gate cross-provider-exec --avoid none "Run this gate on any available target"
+```
+
+## Failure behavior
+
+Gate failure behavior is owned by the gate-aware skill:
+
+| `onFailure` | Meaning                                                                              |
+| ----------- | ------------------------------------------------------------------------------------ |
+| `block`     | Read the gate output, attempt remediation, rerun up to `maxAttempts`, then escalate. |
+| `prompt`    | Surface the failure and ask the user how to proceed.                                 |
+| `warn`      | Record the failure and continue.                                                     |
+
+`cross-provider-exec` does fallback only before dispatch, while selecting an
+available target. Once a target actually runs, its exit code is the gate result;
+OAT does not try another target after a failed review.
+
+## Current limits
+
+V1 gates avoid the current runtime, not the current model or effort setting.
+Same-runtime but different-target dispatch, such as using Cursor again with a
+different model slug, is future work. Until that exists, use `--target <id>` when
+you need an explicit reviewer target, or rely on the default `same-runtime`
+avoidance for cross-runtime review.

package/assets/docs/contributing/design-principles.md

@@ -71,7 +71,7 @@ packages/cli/src/
 ## Runtime Bootstrap and Flags
 
 - Startup order: load runtime config -> validate env/input -> build command context -> register commands.
-- Register global flags early and consistently (`--json`, `--verbose`, `--scope`, `--cwd`).
+- Register global flags early and consistently (`--json`, `--verbose`, `--cwd`). Scope-aware commands take `--scope` as a per-command option (via the shared `withScopeOption` helper), not a global flag, so it appears in `--help` only on the commands that actually consume it.
 
 ## UX and Output Principles
 

package/assets/docs/contributing/skills.md

@@ -41,6 +41,7 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - `disable-model-invocation`
 - `user-invocable`
 - `allowed-tools`
+- `oat_gateable`
 
 ## Practical Authoring Flow
 
@@ -76,6 +77,30 @@ At minimum, the skill contract should:
 
 Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
 
+## Gate-aware skills
+
+A skill that supports configured final gates must declare `oat_gateable: true`
+in frontmatter and include a final Gate Execution step in its process contract.
+Without both pieces, a configured `workflow.gates.skills.<skill>` entry is a
+validation warning rather than an executable contract.
+
+The Gate Execution step should:
+
+1. Run `oat gate resolve <this-skill> --json`.
+2. Treat `null` as "no gate configured."
+3. Run the resolved `command` as the skill's last step when a gate is present.
+4. Use the command exit code as the pass/fail signal.
+5. Follow the gate's `onFailure` policy:
+   - `block` - remediate and rerun up to `maxAttempts`, then escalate.
+   - `prompt` - surface the failure and ask the user.
+   - `warn` - record the failure and continue.
+
+For cross-runtime review gates, prefer putting
+`oat gate cross-provider-exec "<prompt>"` in the configured gate command rather
+than hard-coding a provider CLI directly in the skill. See
+[Workflow Gates](../cli-utilities/workflow-gates.md) for the config and command
+surface.
+
 ## Reading project state
 
 Skills that need fields from the active project's `state.md` (e.g. `phase`, `phaseStatus`, `workflowMode`, `docsUpdated`, `lastCommit`) MUST query the CLI instead of hand-parsing YAML with `grep`/`awk`.

package/assets/docs/reference/cli-reference.md

@@ -14,6 +14,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
 - [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, and remove bundled OAT skills and agents.
 - [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
+- [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch.
 - [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
 - [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
@@ -45,6 +46,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
 | `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
+| `oat gate ...`                                  | Per-skill final gate config, exec-target registry writes, and cross-runtime prompt dispatch.                                                                                                                               | [Workflow Gates](../cli-utilities/workflow-gates.md)                               |
 | `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                                                                                                | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                                                                                  | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                                                                                            | [Provider Sync](../provider-sync/index.md)                                         |
@@ -66,6 +68,7 @@ Notable commands introduced in the current CLI surface:
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
+- `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command.
 
 ## `oat config` surface flags
 

package/assets/docs/reference/file-locations.md

@@ -22,6 +22,7 @@ For detailed `.oat/` tree semantics, see:
 - Active idea: `activeIdea` in `.oat/config.local.json` (repo) or `~/.oat/config.json` (user)
 - Projects root config: `projects.root` in `.oat/config.json` (read via `oat config get projects.root`)
 - Archive config: `archive.s3Uri`, `archive.s3SyncOnComplete`, `archive.summaryExportPath`, `archive.wrapUpExportPath`, `archive.awsProfile`, and `archive.awsRegion` in `.oat/config.json`
+- Workflow gate config: `workflow.gates.skills` and `workflow.gates.execTargets` in `.oat/config.json`, `.oat/config.local.json`, or `~/.oat/config.json` (manage via `oat gate`)
 - Project manifests/config: `.oat/sync/`
 
 Config discovery via CLI:

package/assets/docs/reference/oat-directory-structure.md

@@ -109,6 +109,8 @@ Current schema keys:
 | `workflow.dispatchCeiling.preset`           | `string`   | unset                    | Convenience preset compiled at write time to concrete per-provider ceilings (`balanced` = codex `high` / claude `sonnet`; `maximum` = codex `xhigh` / claude `opus`; `cost-conscious` = codex `medium` / claude `sonnet`). Stored only when a preset is chosen; runtime reads compiled `providers.*`, never the preset label. |
 | `workflow.dispatchCeiling.providers.codex`  | `string`   | unset                    | Maximum Codex reasoning effort OAT may select through deterministic pinned implementer/reviewer variants (`low`, `medium`, `high`, or `xhigh`). Codex provider default effort is informational for base/unpinned roles and is not treated as this ceiling.                                                                    |
 | `workflow.dispatchCeiling.providers.claude` | `string`   | unset                    | Maximum Claude model tier OAT may select for provider-native subagent dispatch (`haiku`, `sonnet`, or `opus`). Claude has no separate per-dispatch effort axis. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed (no migration).                                             |
+| `workflow.gates.skills`                     | `object`   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                                           |
+| `workflow.gates.execTargets`                | `object`   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                                                   |
 | `archive.s3Uri`                             | `string`   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                                      |
 | `archive.s3SyncOnComplete`                  | `boolean`  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                    |
 | `archive.summaryExportPath`                 | `string`   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                             |
@@ -119,6 +121,7 @@ Current schema keys:
 All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.
 Archive settings are managed via `oat config get/set`, and `oat config describe archive.s3Uri` (or the other archive keys) shows the lifecycle and ownership details from the CLI.
+Workflow gate objects are structured config and are managed with `oat gate`, not the scalar `oat config set` surface. See [Workflow Gates](../cli-utilities/workflow-gates.md).
 
 Example:
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.33",
-  "docs-config": "0.1.33",
-  "docs-theme": "0.1.33",
-  "docs-transforms": "0.1.33"
+  "cli": "0.1.35",
+  "docs-config": "0.1.35",
+  "docs-theme": "0.1.35",
+  "docs-transforms": "0.1.35"
 }

package/assets/skills/oat-project-implement/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: oat-project-implement
-version: 2.0.20
+version: 2.0.21
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
+oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
 disable-model-invocation: true
 user-invocable: true
@@ -1419,6 +1420,27 @@ Final review:
 Next: Create PR or run the oat-project-pr-final skill (when available)
 ```
 
+### Gate Execution
+
+Before reporting this skill as complete, run the configured gate as the final step:
+
+1. Resolve the gate for this skill:
+
+   ```bash
+   oat gate resolve <this-skill> --json
+   ```
+
+   If the command returns JSON `null`, no gate is configured; the skill is complete.
+
+2. If a gate config is returned, run its `command` exactly as configured. Capture stdout, stderr, and the exit code. A zero exit code means the gate passed and the skill is complete.
+
+3. If the command exits nonzero, use `description` to orient the next steps and handle `onFailure`:
+   - `block`: read gate feedback, remediate, and re-run the gate up to `maxAttempts` attempts (default `2`). If attempts are exhausted, escalate to the human with accumulated feedback and append that feedback to `implementation.md`. Treat a launch failure, missing CLI, or no eligible runtime as escalation-biased and do not spend it as a remediation attempt.
+   - `prompt`: surface the gate failure and ask the human how to proceed.
+   - `warn`: record the gate failure and continue.
+
+4. Runtime selection note (V1): the step runs the gate `command` as-is and reads no env var. By default, `oat gate cross-provider-exec` resolves the current host from built-in `hostDetectionCommand`s and avoids the same runtime with zero per-prompt input. It does not read or stamp `OAT_CURRENT_RUNTIME` or `OAT_GATE_EXEC_TARGET`. To pin a specific reviewer for this skill, set `--target <id>` once in that skill's gate `command`; this is the optional precision path and does not require per-prompt input.
+
 ## Success Criteria
 
 - All tasks executed in order

package/assets/skills/oat-project-plan/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: oat-project-plan
-version: 1.3.5
+version: 1.3.6
 description: Use when design.md is complete and executable implementation tasks are needed. Breaks design into bite-sized TDD tasks in canonical plan.md format.
+oat_gateable: true
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
@@ -501,6 +502,27 @@ Total: {N} tasks
 Next: Run oat-project-implement to begin execution.
 ```
 
+### Gate Execution
+
+Before reporting this skill as complete, run the configured gate as the final step:
+
+1. Resolve the gate for this skill:
+
+   ```bash
+   oat gate resolve <this-skill> --json
+   ```
+
+   If the command returns JSON `null`, no gate is configured; the skill is complete.
+
+2. If a gate config is returned, run its `command` exactly as configured. Capture stdout, stderr, and the exit code. A zero exit code means the gate passed and the skill is complete.
+
+3. If the command exits nonzero, use `description` to orient the next steps and handle `onFailure`:
+   - `block`: read gate feedback, remediate, and re-run the gate up to `maxAttempts` attempts (default `2`). If attempts are exhausted, escalate to the human with accumulated feedback and append that feedback to `implementation.md`. Treat a launch failure, missing CLI, or no eligible runtime as escalation-biased and do not spend it as a remediation attempt.
+   - `prompt`: surface the gate failure and ask the human how to proceed.
+   - `warn`: record the gate failure and continue.
+
+4. Runtime selection note (V1): the step runs the gate `command` as-is and reads no env var. By default, `oat gate cross-provider-exec` resolves the current host from built-in `hostDetectionCommand`s and avoids the same runtime with zero per-prompt input. It does not read or stamp `OAT_CURRENT_RUNTIME` or `OAT_GATE_EXEC_TARGET`. To pin a specific reviewer for this skill, set `--target <id>` once in that skill's gate `command`; this is the optional precision path and does not require per-prompt input.
+
 ## Success Criteria
 
 - All design components covered by tasks

package/dist/app/create-program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-program.d.ts","sourceRoot":"","sources":["../../src/app/create-program.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAO5C,wBAAgB,aAAa,IAAI,OAAO,CAavC"}
+{"version":3,"file":"create-program.d.ts","sourceRoot":"","sources":["../../src/app/create-program.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,aAAa,IAAI,OAAO,CASvC"}

package/dist/app/create-program.js

@@ -1,8 +1,7 @@
 import { OAT_VERSION } from '../shared/oat-version.js';
-import { Command, Option } from 'commander';
+import { Command } from 'commander';
 const PROGRAM_NAME = 'oat';
 const PROGRAM_DESCRIPTION = 'Open Agent Toolkit CLI for provider interoperability';
-const SCOPE_CHOICES = ['project', 'user', 'all'];
 export function createProgram() {
     return new Command()
         .name(PROGRAM_NAME)
@@ -10,8 +9,6 @@ export function createProgram() {
         .version(OAT_VERSION)
         .option('--json', 'Output a single JSON document')
         .option('--verbose', 'Enable verbose debug output')
-        .addOption(new Option('--scope <scope>', 'Limit execution scope')
-        .choices([...SCOPE_CHOICES])
-        .default('all'))
-        .option('--cwd <path>', 'Override working directory');
+        .option('--cwd <path>', 'Override working directory')
+        .configureHelp({ showGlobalOptions: true });
 }

package/dist/app/help-config.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+/**
+ * Commander's `.addCommand()` does not inherit the parent's help configuration.
+ * This recursive helper applies `showGlobalOptions: true` to every node in the
+ * command tree after registration, so that each subcommand's `--help` output
+ * includes a "Global Options" section showing `--json`, `--verbose`, and `--cwd`.
+ *
+ * Must be called once at the end of `registerCommands(program)` after all
+ * subcommands have been added via `.addCommand()`.
+ */
+export declare function applyHelpConfiguration(command: Command): void;
+//# sourceMappingURL=help-config.d.ts.map

package/dist/app/help-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-config.d.ts","sourceRoot":"","sources":["../../src/app/help-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK7D"}

package/dist/app/help-config.js

@@ -0,0 +1,15 @@
+/**
+ * Commander's `.addCommand()` does not inherit the parent's help configuration.
+ * This recursive helper applies `showGlobalOptions: true` to every node in the
+ * command tree after registration, so that each subcommand's `--help` output
+ * includes a "Global Options" section showing `--json`, `--verbose`, and `--cwd`.
+ *
+ * Must be called once at the end of `registerCommands(program)` after all
+ * subcommands have been added via `.addCommand()`.
+ */
+export function applyHelpConfiguration(command) {
+    command.configureHelp({ showGlobalOptions: true });
+    for (const sub of command.commands) {
+        applyHelpConfiguration(sub);
+    }
+}

package/dist/commands/doctor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAInE,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAM9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,gBAAgB,EAAE,CAChB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,cAAc,EAAE,CACd,SAAS,EAAE,MAAM,KACd,OAAO,CACV,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CACnE,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC3C,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAED,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0BAA0B,EAAE,MAAM,CAAC;IACnC,cAAc,EAAE,oBAAoB,EAAE,CAAC;CACxC;AAsbD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAC1C,OAAO,CAcT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAInE,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAM9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,gBAAgB,EAAE,CAChB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,MAAM,CAAC,CAAC;IACrB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1D,mBAAmB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D,cAAc,EAAE,CACd,SAAS,EAAE,MAAM,KACd,OAAO,CACV,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CACnE,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,kBAAkB,EAAE,CAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5B,kBAAkB,EAAE,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,KAC3C,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClC;AAED,UAAU,oBAAoB;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,UAAU,kBAAkB;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0BAA0B,EAAE,MAAM,CAAC;IACnC,cAAc,EAAE,oBAAoB,EAAE,CAAC;CACxC;AAsbD,wBAAgB,mBAAmB,CACjC,SAAS,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAC1C,OAAO,CAcT"}

package/dist/commands/doctor/index.js

@@ -5,6 +5,7 @@ import { buildCommandContext, } from '../../app/command-context.js';
 import { compareVersions } from '../init/tools/shared/version.js';
 import { createPjmDisabledCheck, runPjmDoctorChecks, } from '../pjm/doctor.js';
 import { getSkillVersion } from '../shared/frontmatter.js';
+import { withScopeOption } from '../shared/scope-option.js';
 import { readGlobalOptions, resolveConcreteScopes, } from '../shared/shared.utils.js';
 import { readOatConfig } from '../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
@@ -379,7 +380,7 @@ export function createDoctorCommand(overrides = {}) {
         ...createDependencies(),
         ...overrides,
     };
-    return new Command('doctor')
+    return withScopeOption(new Command('doctor'))
         .description('Run environment and setup diagnostics')
         .action(async (_options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

package/dist/commands/gate/index.d.ts

@@ -0,0 +1,35 @@
+import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
+import { type ExecTarget, type OatConfig, type OatLocalConfig, type UserConfig } from '../../config/oat-config.js';
+import { type ResolvedConfig } from '../../config/resolve.js';
+import { Command } from 'commander';
+interface GateCommandDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    resolveProjectRoot: (cwd: string) => Promise<string>;
+    readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    writeOatConfig: (repoRoot: string, config: OatConfig) => Promise<void>;
+    readOatLocalConfig: (repoRoot: string) => Promise<OatLocalConfig>;
+    writeOatLocalConfig: (repoRoot: string, config: OatLocalConfig) => Promise<void>;
+    readUserConfig: (userConfigDir: string) => Promise<UserConfig>;
+    writeUserConfig: (userConfigDir: string, config: UserConfig) => Promise<void>;
+    resolveEffectiveConfig: (repoRoot: string, userConfigDir: string, env: NodeJS.ProcessEnv) => Promise<ResolvedConfig>;
+    runProcess: (command: string, args: string[], options: ProcessRunOptions) => Promise<ProcessRunResult>;
+    processEnv: NodeJS.ProcessEnv;
+}
+interface ProcessRunOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    purpose: 'host-detection' | 'availability' | 'execute';
+    stdio: 'ignore' | 'inherit';
+}
+interface ProcessRunResult {
+    exitCode: number;
+}
+type CrossProviderAvoid = 'same-runtime' | 'none';
+export interface SelectedExecTarget {
+    id: string;
+    target: ExecTarget;
+}
+export declare function selectExecTarget(registry: Readonly<Record<string, ExecTarget>>, currentRuntime: string, avoid: CrossProviderAvoid): SelectedExecTarget | null;
+export declare function createGateCommand(overrides?: Partial<GateCommandDependencies>): Command;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/gate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAQL,KAAK,UAAU,EAIf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,uBAAuB;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE,mBAAmB,EAAE,CACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,cAAc,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,cAAc,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/D,eAAe,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,EAAE,CACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAmCD,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,EAAE,gBAAgB,GAAG,cAAc,GAAG,SAAS,CAAC;IACvD,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC7B;AAED,UAAU,gBAAgB;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,kBAAkB,GAAG,cAAc,GAAG,MAAM,CAAC;AAKlD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAmWD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,EAC9C,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,kBAAkB,GACxB,kBAAkB,GAAG,IAAI,CAE3B;AA2SD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAoIT"}