@open-agent-toolkit/cli 0.1.34 → 0.1.36

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.2
+version: 1.1.3
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -54,6 +54,7 @@ You will be given a "Review Scope" block including:
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
 - **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
 - **oat_output_mode**: Optional output-sink selector. Absent (or any value other than `structured`) means **artifact mode** — write the review artifact to disk per Step 8. `structured` means **structured-output mode** — return a `StructuredFindings` object in-memory and write NO artifact file (see **Structured-Output Mode**). This key parallels the existing `oat_review_invocation` dispatch-payload naming.
+- **oat_review_invocation**: Optional provenance selector for artifact-mode reviews. Use `manual`, `auto`, or `gate`; default to `manual` when absent.
 - **model_axis**: Optional model dispatch state selected by the orchestrator (`selected:<value>`, `inherited`, `not-applicable`, or `host-auto`)
 - **effort_axis**: Optional effort dispatch state selected by the orchestrator (`selected:<value>`, `provider-default`, `inherited`, `not-applicable`, or `host-auto`)
 - **dispatch_ceiling**: Optional resolved provider ceiling that capped/selected this review dispatch
@@ -264,6 +265,12 @@ Group findings by severity:
 - Missing tests for important paths
 - Stale spec/design/plan artifact that conflicts with a defensible implementation and should be aligned before closeout
 
+**Medium** (default fix before pass)
+
+- P2 requirements with meaningful behavior or quality impact
+- Moderate maintainability or testability issues
+- Contract gaps that can cause future regressions
+
 **Minor** (fix if time permits)
 
 - P2 requirements
@@ -295,6 +302,7 @@ oat_generated: true
 oat_generated_at: YYYY-MM-DD
 oat_review_scope: { scope }
 oat_review_type: { code|artifact|analysis }
+oat_review_invocation: { manual|auto|gate }
 oat_project: { project-path }
 ---
 
@@ -309,6 +317,8 @@ oat_project: { project-path }
 
 {2-3 sentence summary of findings}
 
+Findings: {N} critical, {N} important, {N} medium, {N} minor
+
 ## Findings
 
 ### Critical
@@ -324,6 +334,14 @@ oat_project: { project-path }
 
 {If none: "None"}
 
+- **{Finding title}** (`{file}:{line}`)
+  - Issue: {description}
+  - Fix: {specific guidance}
+
+### Medium
+
+{If none: "None"}
+
 - **{Finding title}** (`{file}:{line}`)
   - Issue: {description}
   - Fix: {specific guidance}
@@ -367,6 +385,8 @@ Run the `oat-project-review-receive` skill to convert findings into plan tasks.
 
 ```
 
+Gate parsing contract: artifact-mode reviews, including reviews spawned by `oat gate review`, MUST include either the complete `Findings: {N} critical, {N} important, {N} medium, {N} minor` count line or the standard `## Findings` sections shown above with every severity subsection present.
+
 
 ### Step 9: Return Confirmation
 
@@ -380,7 +400,7 @@ Format:
 ## Review Complete
 
 **Scope:** {scope}
-**Findings:** {N} critical, {N} important, {N} minor
+**Findings:** {N} critical, {N} important, {N} medium, {N} minor
 **Review artifact:** {path}
 
 Return to your main session and run the `oat-project-review-receive` skill.

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

@@ -113,13 +113,19 @@ 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 review <prompt...>` - run a review-specific gate and map blocking review findings to exit status
 - `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`.
+Use `oat gate review` for OAT review gates. It keeps the normal stateful
+review-provider workflow: the review artifact, Reviews row update, and review
+bookkeeping commits are expected, and the produced review must be received with
+`oat-project-review-receive` before the host treats it as dispositioned.
+
+Use `oat gate cross-provider-exec` for generic cross-runtime execution. It
+avoids the current runtime by default, chooses a fresh Codex, Claude, or Cursor
+target when available, and exits with the child process status. 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).
 

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

@@ -7,11 +7,14 @@ description: Configure per-skill final commands and cross-runtime review dispatc
 
 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.
+the work, then `oat gate review` dispatches a normal OAT review to another
+runtime such as Codex or Claude and maps blocking review findings to the gate
+exit status.
 
-V1 gates are deliberately thin. A gate command passes or fails by exit code, and
-the skill owns what to do next.
+`oat gate cross-provider-exec` remains the generic child-status executor. It
+selects an exec target, runs the prompt, and exits with the child process
+status. Use `oat gate review` when the command is specifically an OAT review
+gate that should inspect the produced review artifact.
 
 ## Gate config
 
@@ -23,7 +26,7 @@ Gate config lives under `workflow.gates.skills` and is keyed by skill name.
     "gates": {
       "skills": {
         "oat-project-implement": {
-          "command": "oat gate cross-provider-exec \"Use oat-project-review-provide to review the current project\"",
+          "command": "oat gate review \"Use oat-project-review-provide code final to review the current project\"",
           "description": "Run a fresh-runtime final review before implementation is considered done.",
           "onFailure": "block",
           "maxAttempts": 2
@@ -41,11 +44,33 @@ Fields:
 - `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-project-plan`, `oat-project-implement`, `oat-project-quick-start`, and
+`oat-project-import-plan` 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.
 
+## Review gates
+
+`oat gate review` is intentionally stateful. It is equivalent to running
+`oat-project-review-provide` in another terminal or provider, so the normal
+review side effects are expected:
+
+- a review artifact is written under the project reviews directory
+- the plan Reviews row is updated
+- review bookkeeping commits are expected when the review workflow changes
+  tracked state
+
+Gate-produced review artifacts use `oat_review_invocation: gate` in
+frontmatter. After a gate review reports a produced artifact, the host must run
+or hand off to `oat-project-review-receive` before treating the review as
+dispositioned. Until receive runs, the artifact is only produced, not consumed.
+
+`oat gate review` parses the produced artifact and returns a blocking exit
+status when the configured threshold is met. `cross-provider-exec` does not do
+that interpretation; for generic prompts it still returns only the child process
+status.
+
 ## Exec targets
 
 `oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.
@@ -55,11 +80,16 @@ 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`                          |
+| 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"]` | `CURSOR_AGENT`                          |
+
+Built-in targets are conservative defaults. Trusted noninteractive gates that
+need to run tools without hanging on provider approval prompts should be
+configured deliberately in `workflow.gates.execTargets`; OAT should not bake
+dangerous provider permission flags into built-ins.
 
 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
@@ -71,12 +101,54 @@ oat gate target set claude-opus \
   --base-command-json '["claude","-p","--model","opus"]' \
   --availability-json '["claude","--version"]' \
   --priority 90 \
-  --user
+  --layer user
 ```
 
 JSON argv is intentional: provider commands often contain flags such as `-p` or
 `--model`, which would be ambiguous as variadic CLI options.
 
+### Trusted target examples
+
+Use these examples only in trusted environments where the provider process may
+read files, run tools, and write review bookkeeping without an interactive
+approval prompt. They are user-level target configuration, not built-in OAT
+defaults.
+
+Claude's default permission mode can block on
+`Skill(oat-project-review-provide)`, `oat`, `pnpm`, and shell or tool calls. A
+trusted user can opt into `--dangerously-skip-permissions` or the equivalent
+`--permission-mode bypassPermissions` behavior in their target command.
+
+Codex trusted gate automation should make sandbox and approval bypass explicit
+with `--dangerously-bypass-approvals-and-sandbox`, even when the user's current
+default profile already permits the needed commands.
+
+Cursor trusted automation should use `--force`; `--yolo` is the documented alias
+for the same behavior.
+
+```bash
+oat gate target set codex-5.5-xhigh \
+  --runtime codex \
+  --base-command-json '["codex","exec","--model","gpt-5.5","-c","model_reasoning_effort=\"xhigh\"","--dangerously-bypass-approvals-and-sandbox"]' \
+  --availability-json '["codex","--version"]' \
+  --priority 120 \
+  --layer user
+
+oat gate target set claude-opus-skip-permissions \
+  --runtime claude \
+  --base-command-json '["claude","-p","--model","opus","--dangerously-skip-permissions"]' \
+  --availability-json '["claude","--version"]' \
+  --priority 115 \
+  --layer user
+
+oat gate target set cursor-force \
+  --runtime cursor \
+  --base-command-json '["cursor-agent","-p","--force"]' \
+  --availability-json '["cursor-agent","--version"]' \
+  --priority 90 \
+  --layer user
+```
+
 ## Command surface
 
 Inspect a skill gate:
@@ -89,13 +161,13 @@ 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"' \
+  --command 'oat gate review --target codex-5.5-xhigh --review-type code --review-scope final "Use oat-project-review-provide code final to review the current project"' \
   --description "Run final review in another runtime" \
   --on-failure block \
   --max-attempts 2 \
-  --user
+  --layer user
 
-oat gate unset oat-project-implement --user
+oat gate unset oat-project-implement --layer user
 ```
 
 Set or clear an exec target:
@@ -106,12 +178,24 @@ oat gate target set codex-high \
   --base-command-json '["codex","exec","--model","gpt-5.5"]' \
   --availability-json '["codex","--version"]' \
   --priority 90 \
-  --user
+  --layer user
+
+oat gate target unset codex-high --layer user
+```
 
-oat gate target unset codex-high --user
+Dispatch a review through the target registry:
+
+```bash
+oat gate review --target codex-5.5-xhigh \
+  --review-type code \
+  --review-scope final \
+  "Use oat-project-review-provide code final to review the current project"
 ```
 
-Dispatch a prompt through the target registry:
+Leaving `--target` unset lets target priority choose the highest-priority
+available non-host runtime.
+
+Dispatch a generic prompt through the target registry:
 
 ```bash
 oat gate cross-provider-exec "Use oat-project-review-provide to review the current project"

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/reference/cli-reference.md

@@ -14,7 +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.
+- [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt 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.
@@ -46,7 +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 gate ...`                                  | Per-skill final gate config, review-specific gate execution, 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)                                         |
@@ -68,7 +68,8 @@ 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 gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings; produced gate reviews use `oat_review_invocation: gate` and still require `oat-project-review-receive` handoff before they are dispositioned.
+- `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 and exit with the child status.
 
 ## `oat config` surface flags
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.34",
-  "docs-config": "0.1.34",
-  "docs-theme": "0.1.34",
-  "docs-transforms": "0.1.34"
+  "cli": "0.1.36",
+  "docs-config": "0.1.36",
+  "docs-theme": "0.1.36",
+  "docs-transforms": "0.1.36"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.21
+version: 2.0.22
 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]'
@@ -1434,12 +1434,16 @@ Before reporting this skill as complete, run the configured gate as the final st
 
 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`:
+3. Review-artifact handoff:
+   - If the gate reports a produced review artifact, the host must run `oat-project-review-receive` to receive and disposition that artifact before treating the review as consumed.
+   - This applies to `oat gate review ...` outputs regardless of whether the gate ultimately exits zero or nonzero; the command output owns the exact artifact path, and receive-review owns disposition and archival.
+
+4. 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.
+5. 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
 

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

@@ -1,8 +1,9 @@
 ---
 name: oat-project-import-plan
-version: 1.4.0
+version: 1.4.1
 description: Use when you have an external markdown plan to execute with OAT. Preserves the source plan and normalizes it into canonical plan.md format.
 argument-hint: '<path-to-plan.md> [--provider codex|cursor|claude] [--project <name>]'
+oat_gateable: true
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
@@ -56,14 +57,15 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print step indicators, e.g.:
-  - `[0/7] Checking inherited git state...`
-  - `[1/7] Resolving project + source plan…`
-  - `[2/7] Preserving imported source…`
-  - `[3/7] Normalizing plan to OAT task structure…`
-  - `[4/7] Updating plan metadata…`
-  - `[5/7] Running import-aware plan review…`
-  - `[6/7] Updating project state + dashboard…`
-  - `[7/7] Ensuring implementation tracker…`
+  - `[0/8] Checking inherited git state...`
+  - `[1/8] Resolving project + source plan…`
+  - `[2/8] Preserving imported source…`
+  - `[3/8] Normalizing plan to OAT task structure…`
+  - `[4/8] Updating plan metadata…`
+  - `[5/8] Running import-aware plan review…`
+  - `[6/8] Updating project state + dashboard…`
+  - `[7/8] Ensuring implementation tracker + committing…`
+  - `[8/8] Running configured gate…`
 
 ## Process
 
@@ -255,6 +257,46 @@ If missing, scaffold from template:
 
 Initialize pointer to first plan task ID.
 
+### Step 6.5: Commit Import Artifacts
+
+After the import-aware plan artifact review, project state sync, dashboard refresh, and implementation tracker setup, stage and commit the changed import artifacts before handing off to implementation or stopping.
+
+```bash
+git add "$PROJECT_PATH/references/"
+for path in \
+  "$PROJECT_PATH/plan.md" \
+  "$PROJECT_PATH/implementation.md" \
+  "$PROJECT_PATH/state.md"; do
+  [ -e "$path" ] && git add "$path"
+done
+git diff --cached --quiet || git commit -m "chore(oat): update imported plan artifacts for {project-name}"
+```
+
+### Gate Execution
+
+Before reporting this skill as complete, run the configured gate as the final step after artifact review, state sync, dashboard refresh, and the import artifact commit:
+
+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. Review-artifact handoff:
+   - If the gate reports a produced review artifact, the host must run `oat-project-review-receive` to receive and disposition that artifact before treating the review as consumed.
+   - This applies to `oat gate review ...` outputs regardless of whether the gate ultimately exits zero or nonzero; the command output owns the exact artifact path, and receive-review owns disposition and archival.
+
+4. 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.
+
+5. 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.
+
 ### Step 7: Output Next Action
 
 Report:
@@ -280,3 +322,5 @@ Report:
 - ✅ `## Planning Checklist` items left unchecked (HiLL configuration deferred to implementation).
 - ✅ `activeProject` in `.oat/config.local.json` points to the imported project.
 - ✅ `.oat/state.md` has been refreshed locally after pointer update; it is not staged or committed.
+- ✅ Changed import artifacts are committed before handoff or pause.
+- ✅ Configured gate has run, and any produced review artifact has been handed off to `oat-project-review-receive` before it is treated as consumed.

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.6
+version: 1.3.7
 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
@@ -516,12 +516,16 @@ Before reporting this skill as complete, run the configured gate as the final st
 
 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`:
+3. Review-artifact handoff:
+   - If the gate reports a produced review artifact, the host must run `oat-project-review-receive` to receive and disposition that artifact before treating the review as consumed.
+   - This applies to `oat gate review ...` outputs regardless of whether the gate ultimately exits zero or nonzero; the command output owns the exact artifact path, and receive-review owns disposition and archival.
+
+4. 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.
+5. 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
 

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: oat-project-quick-start
-version: 2.1.6
+version: 2.1.7
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
+oat_gateable: true
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
@@ -57,14 +58,15 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print step indicators, e.g.:
-  - `[0/7] Checking inherited git state...`
-  - `[1/7] Scaffolding quick-mode project…`
-  - `[2/7] Exploring solution space + capturing discovery…`
-  - `[3/7] Decision point: design depth…`
-  - `[4/7] Generating execution plan…`
-  - `[5/7] Running plan artifact review…`
-  - `[6/7] Initializing implementation tracker…`
-  - `[7/7] Refreshing dashboard…`
+  - `[0/8] Checking inherited git state...`
+  - `[1/8] Scaffolding quick-mode project…`
+  - `[2/8] Exploring solution space + capturing discovery…`
+  - `[3/8] Decision point: design depth…`
+  - `[4/8] Generating execution plan…`
+  - `[5/8] Running plan artifact review…`
+  - `[6/8] Initializing implementation tracker…`
+  - `[7/8] Refreshing dashboard + committing…`
+  - `[8/8] Running configured gate…`
   - _(If lightweight design is chosen, insert design steps between 3 and 4)_
 
 ## Artifact Persistence (Required)
@@ -590,6 +592,31 @@ done
 git diff --cached --quiet || git commit -m "chore(oat): update quick-start artifacts for {project-name}"
 ```
 
+### Gate Execution
+
+Before reporting this skill as complete, run the configured gate as the final step after artifact review, state sync, dashboard refresh, and the quick-start artifact commit:
+
+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. Review-artifact handoff:
+   - If the gate reports a produced review artifact, the host must run `oat-project-review-receive` to receive and disposition that artifact before treating the review as consumed.
+   - This applies to `oat gate review ...` outputs regardless of whether the gate ultimately exits zero or nonzero; the command output owns the exact artifact path, and receive-review owns disposition and archival.
+
+4. 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.
+
+5. 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.
+
 ### Step 7: Output Next Action
 
 Report:
@@ -611,3 +638,4 @@ Report:
 - ✅ `plan.md` records the plan artifact review row unless `workflow.autoArtifactReview.plan` was explicitly disabled.
 - ✅ `implementation.md` is initialized for resumable execution.
 - ✅ Changed quick-start artifacts are committed before handoff or pause; `.oat/state.md` is refreshed locally when available.
+- ✅ Configured gate has run, and any produced review artifact has been handed off to `oat-project-review-receive` before it is treated as consumed.

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: oat-project-review-provide
-version: 1.3.7
+version: 1.3.8
 description: Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
 disable-model-invocation: false
 user-invocable: true
-allowed-tools: Read, Glob, Grep, Bash(git:*), AskUserQuestion
+allowed-tools: Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Bash(mkdir:*), Bash(date:*), Bash(realpath:*), Bash(awk:*), AskUserQuestion
 ---
 
 # Request Review
@@ -639,7 +639,7 @@ oat_generated: true
 oat_generated_at: { today }
 oat_review_scope: { scope }
 oat_review_type: { code|artifact }
-oat_review_invocation: { manual|auto }
+oat_review_invocation: { manual|auto|gate }
 oat_project: { PROJECT_PATH }
 ---
 
@@ -655,13 +655,21 @@ oat_project: { PROJECT_PATH }
 
 - `manual` (default): Review was manually triggered by the user. `oat-project-review-receive` uses standard disposition behavior (user prompts for triage, minors auto-deferred for non-final scopes).
 - `auto`: Review was spawned by the auto-review checkpoint trigger in `oat-project-implement`. `oat-project-review-receive` uses relaxed disposition: minors are auto-converted to fix tasks (not deferred), no user prompts for disposition decisions.
+- `gate`: Review was spawned by `oat gate review`. Gate-originated reviews use normal stateful review-provide behavior: write the review artifact, update the `## Reviews` row, and commit review bookkeeping. `oat-project-review-receive` treats gate reviews with the same standard disposition behavior as manual reviews unless a future implementation explicitly designs autonomous receive.
 
-When `oat-project-implement` spawns this skill for auto-review at checkpoints, it passes context indicating auto invocation. Set `oat_review_invocation: auto` in the artifact frontmatter. For all other invocations (user-triggered, fresh session), use `manual`.
+When `oat-project-implement` spawns this skill for auto-review at checkpoints, it passes context indicating auto invocation. Set `oat_review_invocation: auto` in the artifact frontmatter. When `oat gate review` spawns this skill, set `oat_review_invocation: gate`. For all other invocations (user-triggered, fresh session), use `manual`.
+
+Gate parsing contract:
+
+- Include either the `Findings: {N} critical, {N} important, {N} medium, {N} minor` summary line or the standard `## Findings` section with `### Critical`, `### Important`, `### Medium`, and `### Minor` subsections populated with findings or `None`.
+- Do not omit severity headings merely because a severity has zero findings; `oat gate review` depends on counts or standard Findings sections to determine whether the review blocks.
 
 ## Summary
 
 {2-3 sentence summary}
 
+Findings: {N} critical, {N} important, {N} medium, {N} minor
+
 ## Findings
 
 ### Critical

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.5.3
+version: 1.5.4
 description: Use when the user explicitly asks to receive review findings for an OAT project — e.g. "receive review", "process review", "process the project review", or confirms a previously offered review-receive step. Do NOT auto-invoke merely because a review file exists. Resolves the latest review and offers before acting.
 disable-model-invocation: false
 user-invocable: true
@@ -274,6 +274,8 @@ Read `oat_review_type` and `oat_review_invocation` from review artifact frontmat
     - **No user prompts for disposition decisions.** The auto-review path runs fully autonomously.
     - Genuinely ambiguous findings (e.g., a medium the agent disagrees with) are deferred with a note explaining why, rather than pausing for interactive resolution.
   - Follow the task-conversion flow in Steps 3-10 with these adjusted defaults.
+- If `oat_review_type == code` AND `oat_review_invocation == gate`:
+  - **Gate review mode.** This review was spawned by `oat gate review`, but receive remains standard disposition behavior. Treat `gate` the same as manual for prompts, finding conversion, artifact archival, and bookkeeping unless a future implementation explicitly designs an autonomous receive path.
 - If `oat_review_type == code` (manual or `oat_review_invocation` absent):
   - Follow the existing task-conversion flow in Steps 3-10 with standard disposition behavior.