@open-agent-toolkit/cli 0.1.35 → 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/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/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.35",
-  "docs-config": "0.1.35",
-  "docs-theme": "0.1.35",
-  "docs-transforms": "0.1.35"
+  "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.
 

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAO9B,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;AAGzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,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;AA0CD,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;AAMlD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,CAAC;CACpB;AAkZD,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;AA+wBD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwKT"}

package/dist/commands/gate/index.js

@@ -1,11 +1,16 @@
 import { spawn } from 'node:child_process';
-import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative } from 'node:path';
 import { buildCommandContext, } from '../../app/command-context.js';
+import { getFrontmatterBlock, getFrontmatterField, } from '../shared/frontmatter.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { BUILTIN_EXEC_TARGETS, readOatConfig, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
 import { resolveEffectiveConfig, resolveExecTargets, resolveGate, } from '../../config/resolve.js';
-import { resolveProjectRoot } from '../../fs/paths.js';
+import { dirExists, fileExists } from '../../fs/io.js';
+import { normalizeToPosixPath, resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { parseReviewGateVerdict, } from './review-verdict.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
@@ -29,6 +34,16 @@ const VALID_CROSS_PROVIDER_AVOIDS = [
     'same-runtime',
     'none',
 ];
+const VALID_REVIEW_GATE_THRESHOLDS = [
+    'critical',
+    'important',
+    'medium',
+    'minor',
+];
+const REVIEW_GATE_CONTEXT_NOTE = 'This review is gate-originated. If you run `oat-project-review-provide`, set `oat_review_invocation: gate` in the review artifact.';
+function reviewGateProjectContext(projectPath) {
+    return `Resolved OAT project path: ${projectPath}. Run the review for this project path.`;
+}
 async function runChildProcess(command, args, options) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, {
@@ -90,6 +105,13 @@ function parseCrossProviderAvoid(value) {
     }
     return avoid;
 }
+function parseReviewGateThreshold(value) {
+    const threshold = value?.trim() || 'important';
+    if (!VALID_REVIEW_GATE_THRESHOLDS.includes(threshold)) {
+        throw new Error('--exit-nonzero-on must be one of critical | important | medium | minor.');
+    }
+    return threshold;
+}
 function parseOnFailure(value) {
     if (!value || !VALID_ON_FAILURE.includes(value)) {
         throw new Error('--on-failure must be one of block | prompt | warn.');
@@ -149,6 +171,15 @@ function parseGateConfig(options) {
             : {}),
     };
 }
+function detectDevBuildGateCommandWarnings(command) {
+    const normalized = command.trim();
+    if (!/^node\s+(?:"[^"]*\/packages\/cli\/dist\/index\.js"|'[^']*\/packages\/cli\/dist\/index\.js'|\S*\/packages\/cli\/dist\/index\.js)\s+gate(?:\s|$)/.test(normalized)) {
+        return [];
+    }
+    return [
+        'Durable docs/config should reference `oat gate ...`; absolute dev-build paths are reserved for local development of unmerged behavior.',
+    ];
+}
 function parseExecTargetConfig(options) {
     if (options.disable) {
         return null;
@@ -299,6 +330,23 @@ async function selectAvailableExecTarget(registry, currentRuntime, avoid, contex
     }
     return null;
 }
+async function resolveSelectedExecTarget(targets, options, context, dependencies) {
+    const explicitTarget = options.target?.trim();
+    if (explicitTarget) {
+        const target = targets[explicitTarget];
+        if (!target) {
+            throw new Error(`Unknown exec target "${explicitTarget}".`);
+        }
+        return { id: explicitTarget, target: cloneExecTarget(target) };
+    }
+    const avoid = parseCrossProviderAvoid(options.avoid);
+    const currentRuntime = await resolveCurrentRuntime(options.currentRuntime, context, dependencies);
+    const selected = await selectAvailableExecTarget(targets, currentRuntime, avoid, context, dependencies);
+    if (!selected) {
+        throw new Error(noEligibleTargetMessage(currentRuntime, avoid));
+    }
+    return selected;
+}
 async function executeTarget(selected, prompt, context, dependencies) {
     const [command, baseArgs] = argvHead(selected.target.baseCommand);
     if (!command) {
@@ -321,6 +369,217 @@ async function executeTarget(selected, prompt, context, dependencies) {
 function noEligibleTargetMessage(currentRuntime, avoid) {
     return `No eligible gate exec target found for current runtime "${currentRuntime}" with --avoid ${avoid}. Install or configure an alternate runtime, rerun with --avoid none, or pin a target with --target <id>.`;
 }
+function normalizeRepoRelativeProjectPath(repoRoot, pathValue) {
+    const trimmed = pathValue.trim().replace(/\/+$/, '');
+    const withoutState = trimmed.endsWith('/state.md')
+        ? trimmed.slice(0, -'/state.md'.length)
+        : trimmed;
+    const repoRelative = isAbsolute(withoutState)
+        ? relative(repoRoot, withoutState)
+        : withoutState;
+    const normalized = normalizeToPosixPath(repoRelative).replace(/^\.\//, '');
+    if (normalized === '..' || normalized.startsWith('../')) {
+        throw new Error(`Project path must resolve inside the current repository: ${pathValue}`);
+    }
+    return normalized;
+}
+async function listProjectCandidates(repoRoot, projectsRoot) {
+    const normalizedProjectsRoot = normalizeRepoRelativeProjectPath(repoRoot, projectsRoot);
+    const absoluteProjectsRoot = join(repoRoot, normalizedProjectsRoot);
+    let scopeEntries;
+    try {
+        scopeEntries = await readdir(absoluteProjectsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const candidates = (await Promise.all(scopeEntries
+        .filter((entry) => entry.isDirectory())
+        .map(async (scopeEntry) => {
+        const directProjectPath = normalizeToPosixPath(join(normalizedProjectsRoot, scopeEntry.name));
+        if (await fileExists(join(repoRoot, directProjectPath, 'state.md'))) {
+            return [directProjectPath];
+        }
+        const scopePath = join(absoluteProjectsRoot, scopeEntry.name);
+        const projectEntries = await readdir(scopePath, {
+            withFileTypes: true,
+        });
+        return Promise.all(projectEntries
+            .filter((entry) => entry.isDirectory())
+            .map(async (projectEntry) => {
+            const projectPath = normalizeToPosixPath(join(normalizedProjectsRoot, scopeEntry.name, projectEntry.name));
+            return (await fileExists(join(repoRoot, projectPath, 'state.md')))
+                ? projectPath
+                : null;
+        }));
+    })))
+        .flat()
+        .filter((candidate) => candidate !== null)
+        .sort();
+    return candidates;
+}
+async function assertProjectPath(repoRoot, projectPath, source) {
+    const normalizedPath = normalizeRepoRelativeProjectPath(repoRoot, projectPath);
+    const absolutePath = join(repoRoot, normalizedPath);
+    if (!(await dirExists(absolutePath)) ||
+        !(await fileExists(join(absolutePath, 'state.md')))) {
+        throw new Error(`${source} project "${projectPath}" does not resolve to a project directory containing state.md.`);
+    }
+    return normalizedPath;
+}
+async function resolveExplicitReviewProject(repoRoot, projectsRoot, projectValue) {
+    const trimmed = projectValue.trim();
+    if (!trimmed) {
+        throw new Error('--project must be a non-empty project path or name.');
+    }
+    const looksLikePath = trimmed.includes('/') || trimmed.startsWith('.') || isAbsolute(trimmed);
+    if (looksLikePath) {
+        return assertProjectPath(repoRoot, trimmed, '--project');
+    }
+    const candidates = await listProjectCandidates(repoRoot, projectsRoot);
+    const matches = candidates.filter((candidate) => basename(candidate) === trimmed);
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple OAT projects match --project "${trimmed}": ${matches.join(', ')}. Pass a full project path instead.`);
+    }
+    return assertProjectPath(repoRoot, `${projectsRoot}/${trimmed}`, '--project');
+}
+async function resolveReviewProject(options) {
+    const projectsRoot = String(options.effective.resolved['projects.root']?.value ??
+        options.effective.shared.projects?.root ??
+        '.oat/projects/shared');
+    if (options.project !== undefined) {
+        return resolveExplicitReviewProject(options.repoRoot, projectsRoot, options.project);
+    }
+    const activeProject = options.effective.local.activeProject?.trim();
+    if (activeProject) {
+        return assertProjectPath(options.repoRoot, activeProject, 'Active');
+    }
+    const candidates = await listProjectCandidates(options.repoRoot, projectsRoot);
+    if (candidates.length === 0) {
+        throw new Error('No OAT project could be resolved for gate review. Set an active project or pass --project <path-or-name>.');
+    }
+    if (candidates.length > 1) {
+        throw new Error(`Multiple OAT projects could be resolved for gate review: ${candidates.join(', ')}. Pass --project <path-or-name>.`);
+    }
+    return candidates[0];
+}
+function reviewGateLifecycleRank(scope) {
+    const normalizedScope = scope.trim().toLowerCase();
+    if (normalizedScope === 'final') {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    const phases = [...normalizedScope.matchAll(/p(\d+)/g)].map((match) => Number.parseInt(match[1] ?? '0', 10));
+    if (phases.length === 0) {
+        return 0;
+    }
+    const tasks = [...normalizedScope.matchAll(/(?:^|[-_])t(\d+)/g)].map((match) => Number.parseInt(match[1] ?? '0', 10));
+    const latestPhase = Math.max(...phases);
+    const latestTask = tasks.length > 0 ? Math.max(...tasks) : 9999;
+    return latestPhase * 10_000 + latestTask;
+}
+async function readReviewGateArtifactCandidate(repoRoot, relativePath) {
+    const content = await readFile(join(repoRoot, relativePath), 'utf8');
+    const frontmatter = getFrontmatterBlock(content);
+    if (!frontmatter) {
+        return null;
+    }
+    const generatedAt = getFrontmatterField(frontmatter, 'oat_generated_at');
+    if (!generatedAt) {
+        return null;
+    }
+    const generatedTime = Date.parse(generatedAt);
+    if (Number.isNaN(generatedTime)) {
+        return null;
+    }
+    const scope = getFrontmatterField(frontmatter, 'oat_review_scope') ?? '';
+    return {
+        path: relativePath,
+        scope,
+        generatedAt,
+        kind: 'project',
+        archived: false,
+        actionable: true,
+        generatedTime,
+        lifecycleRank: reviewGateLifecycleRank(scope),
+        signature: createHash('sha256').update(content).digest('hex'),
+    };
+}
+function sortReviewGateArtifacts(left, right) {
+    if (left.generatedTime !== right.generatedTime) {
+        return right.generatedTime - left.generatedTime;
+    }
+    if (left.lifecycleRank !== right.lifecycleRank) {
+        return right.lifecycleRank - left.lifecycleRank;
+    }
+    return left.path.localeCompare(right.path);
+}
+async function listActiveProjectReviewCandidates(options) {
+    const projectPath = normalizeRepoRelativeProjectPath(options.repoRoot, options.projectPath);
+    const reviewsDir = `${projectPath}/reviews`;
+    let entries;
+    try {
+        entries = await readdir(join(options.repoRoot, reviewsDir), {
+            withFileTypes: true,
+        });
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    return (await Promise.all(entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+        .map((entry) => readReviewGateArtifactCandidate(options.repoRoot, normalizeToPosixPath(join(reviewsDir, entry.name))))))
+        .filter((candidate) => candidate !== null)
+        .sort(sortReviewGateArtifacts);
+}
+function findProducedReviewArtifact(before, after) {
+    const beforeSignatures = new Map(before.map((candidate) => [candidate.path, candidate.signature]));
+    return (after.find((candidate) => beforeSignatures.get(candidate.path) !== candidate.signature) ?? null);
+}
+function reviewBlocksAtThreshold(verdict, threshold) {
+    if (verdict.counts.critical > 0) {
+        return true;
+    }
+    if (threshold === 'critical') {
+        return false;
+    }
+    if (verdict.counts.important > 0) {
+        return true;
+    }
+    if (threshold === 'important') {
+        return false;
+    }
+    if (verdict.counts.medium > 0) {
+        return true;
+    }
+    if (threshold === 'medium') {
+        return false;
+    }
+    return verdict.counts.minor > 0;
+}
+function writeReviewGateResult(context, payload) {
+    if (context.json) {
+        context.logger.json(payload);
+        return;
+    }
+    context.logger.info(`Review artifact: ${payload.artifactPath}`);
+    context.logger.info(`Verdict: ${payload.status} (critical=${payload.counts.critical}, important=${payload.counts.important}, medium=${payload.counts.medium}, minor=${payload.counts.minor})`);
+    context.logger.info(payload.handoff);
+}
 async function updateConfigLayer(context, layer, dependencies, mutate) {
     const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
     const userConfigDir = join(context.home, '.oat');
@@ -352,8 +611,21 @@ async function runGateSet(skillName, options, context, dependencies) {
         const layer = parseLayer(options.layer);
         const normalizedSkill = trimRequired(skillName, '<skill>');
         const gate = parseGateConfig(options);
+        const warnings = gate
+            ? detectDevBuildGateCommandWarnings(gate.command)
+            : [];
         await updateConfigLayer(context, layer, dependencies, (config) => setSkillGate(config, normalizedSkill, gate));
-        writeSuccess(context, { layer, skill: normalizedSkill, gate });
+        if (!context.json) {
+            for (const warning of warnings) {
+                context.logger.warn(warning);
+            }
+        }
+        writeSuccess(context, {
+            layer,
+            skill: normalizedSkill,
+            gate,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        });
         process.exitCode = 0;
     }
     catch (error) {
@@ -401,22 +673,71 @@ async function runCrossProviderExec(prompt, options, context, dependencies) {
     try {
         const effective = await readEffectiveConfig(context, dependencies);
         const targets = resolveExecTargets(effective);
-        const explicitTarget = options.target?.trim();
-        if (explicitTarget) {
-            const target = targets[explicitTarget];
-            if (!target) {
-                throw new Error(`Unknown exec target "${explicitTarget}".`);
-            }
-            process.exitCode = await executeTarget({ id: explicitTarget, target: cloneExecTarget(target) }, prompt, context, dependencies);
+        const selected = await resolveSelectedExecTarget(targets, options, context, dependencies);
+        process.exitCode = await executeTarget(selected, prompt, context, dependencies);
+    }
+    catch (error) {
+        writeError(context, error);
+    }
+}
+async function runReviewGate(prompt, options, context, dependencies) {
+    try {
+        const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
+        const userConfigDir = join(context.home, '.oat');
+        const effective = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
+        const projectPath = await resolveReviewProject({
+            repoRoot,
+            effective,
+            project: options.project,
+        });
+        const targets = resolveExecTargets(effective);
+        const selected = await resolveSelectedExecTarget(targets, options, context, dependencies);
+        const threshold = parseReviewGateThreshold(options.exitNonzeroOn);
+        const before = await listActiveProjectReviewCandidates({
+            repoRoot,
+            projectPath,
+        });
+        const reviewPrompt = [
+            REVIEW_GATE_CONTEXT_NOTE,
+            reviewGateProjectContext(projectPath),
+            ...(options.reviewType?.trim()
+                ? [`Review type: ${options.reviewType.trim()}.`]
+                : []),
+            ...(options.reviewScope?.trim()
+                ? [`Review scope: ${options.reviewScope.trim()}.`]
+                : []),
+            ...prompt,
+        ];
+        const childExitCode = await executeTarget(selected, reviewPrompt, context, dependencies);
+        if (childExitCode !== 0) {
+            process.exitCode = childExitCode;
             return;
         }
-        const avoid = parseCrossProviderAvoid(options.avoid);
-        const currentRuntime = await resolveCurrentRuntime(options.currentRuntime, context, dependencies);
-        const selected = await selectAvailableExecTarget(targets, currentRuntime, avoid, context, dependencies);
-        if (!selected) {
-            throw new Error(noEligibleTargetMessage(currentRuntime, avoid));
+        const after = await listActiveProjectReviewCandidates({
+            repoRoot,
+            projectPath,
+        });
+        const producedArtifact = findProducedReviewArtifact(before, after);
+        if (!producedArtifact) {
+            throw new Error(`No new review artifact was detected for project ${projectPath}. Ensure the review provider wrote a project review artifact before the gate exits.`);
         }
-        process.exitCode = await executeTarget(selected, prompt, context, dependencies);
+        const verdict = await parseReviewGateVerdict(join(repoRoot, producedArtifact.path));
+        const blocking = reviewBlocksAtThreshold(verdict, threshold);
+        const handoff = `Run oat-project-review-receive for ${producedArtifact.path} before treating this gate review as consumed.`;
+        writeReviewGateResult(context, {
+            status: blocking ? 'blocked' : 'ok',
+            target: selected.id,
+            project: projectPath,
+            artifactPath: producedArtifact.path,
+            threshold,
+            blocking,
+            counts: verdict.counts,
+            reviewType: verdict.reviewType,
+            scope: verdict.scope,
+            invocation: verdict.invocation,
+            handoff,
+        });
+        process.exitCode = blocking ? 1 : 0;
     }
     catch (error) {
         writeError(context, error);
@@ -470,6 +791,21 @@ export function createGateCommand(overrides = {}) {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         await runCrossProviderExec(prompt, options, context, dependencies);
     });
+    cmd
+        .command('review')
+        .description('Run a review gate and map review findings to exit status')
+        .option('--target <id>', 'Run this exact exec target')
+        .option('--avoid <mode>', 'Avoidance mode: same-runtime or none')
+        .option('--current-runtime <runtime>', 'Override detected runtime for testing or manual routing')
+        .option('--project <path-or-name>', 'Project path or name to review; defaults to the active project')
+        .option('--review-scope <scope>', 'Review scope hint for the provider')
+        .option('--review-type <type>', 'Review type hint for the provider')
+        .option('--exit-nonzero-on <severity>', 'Lowest severity that exits nonzero: critical, important, medium, or minor')
+        .argument('<prompt...>', 'Review prompt arguments appended to the target command')
+        .action(async (prompt, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runReviewGate(prompt, options, context, dependencies);
+    });
     const target = new Command('target').description('Manage gate execution targets');
     target
         .command('set')

package/dist/commands/gate/review-verdict.d.ts

@@ -0,0 +1,15 @@
+export interface ReviewGateVerdict {
+    artifactPath: string;
+    reviewType: 'code' | 'artifact' | 'unknown';
+    scope: string | null;
+    invocation: string | null;
+    counts: {
+        critical: number;
+        important: number;
+        medium: number;
+        minor: number;
+    };
+    blocking: boolean;
+}
+export declare function parseReviewGateVerdict(artifactPath: string): Promise<ReviewGateVerdict>;
+//# sourceMappingURL=review-verdict.d.ts.map

package/dist/commands/gate/review-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-verdict.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/review-verdict.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,QAAQ,EAAE,OAAO,CAAC;CACnB;AA2ND,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAmC5B"}

package/dist/commands/gate/review-verdict.js

@@ -0,0 +1,180 @@
+import { readFile } from 'node:fs/promises';
+import { getFrontmatterBlock } from '../shared/frontmatter.js';
+import YAML from 'yaml';
+const SEVERITIES = [
+    'critical',
+    'important',
+    'medium',
+    'minor',
+];
+const FRONTMATTER_COUNT_KEYS = {
+    critical: ['oat_review_critical_count', 'critical'],
+    important: ['oat_review_important_count', 'important'],
+    medium: ['oat_review_medium_count', 'medium'],
+    minor: ['oat_review_minor_count', 'minor'],
+};
+function normalizeReviewType(value) {
+    return value === 'code' || value === 'artifact' ? value : 'unknown';
+}
+function stringOrNull(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function parseCountValue(value) {
+    const numberValue = typeof value === 'number'
+        ? value
+        : typeof value === 'string'
+            ? Number(value.trim())
+            : Number.NaN;
+    if (!Number.isInteger(numberValue) || numberValue < 0) {
+        return null;
+    }
+    return numberValue;
+}
+function readFrontmatterCounts(frontmatter) {
+    const nestedCounts = typeof frontmatter['oat_review_counts'] === 'object' &&
+        frontmatter['oat_review_counts'] !== null &&
+        !Array.isArray(frontmatter['oat_review_counts'])
+        ? frontmatter['oat_review_counts']
+        : null;
+    const counts = {
+        critical: 0,
+        important: 0,
+        medium: 0,
+        minor: 0,
+    };
+    for (const severity of SEVERITIES) {
+        const candidateValues = [
+            ...FRONTMATTER_COUNT_KEYS[severity].map((key) => frontmatter[key]),
+            ...(nestedCounts
+                ? FRONTMATTER_COUNT_KEYS[severity].map((key) => nestedCounts[key])
+                : []),
+        ].filter((value) => value !== undefined && value !== null);
+        if (candidateValues.length === 0) {
+            return null;
+        }
+        const parsedCount = candidateValues.reduce((parsed, value) => {
+            if (parsed !== null) {
+                return parsed;
+            }
+            return parseCountValue(value);
+        }, null);
+        if (parsedCount === null) {
+            return null;
+        }
+        counts[severity] = parsedCount;
+    }
+    return counts;
+}
+function sectionContentIsEmpty(content) {
+    const cleaned = content
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !/^<!--.*-->$/.test(line))
+        .join('\n')
+        .trim();
+    return cleaned.length === 0 || /^none\.?$/i.test(cleaned);
+}
+function countFindingsInSection(content) {
+    if (sectionContentIsEmpty(content)) {
+        return 0;
+    }
+    return content
+        .split('\n')
+        .filter((line) => /^([-*+]\s+\S|\d+\.\s+\S)/.test(line)).length;
+}
+function normalizeHeading(value) {
+    const normalized = value.trim().toLowerCase();
+    if (SEVERITIES.includes(normalized)) {
+        return normalized;
+    }
+    return null;
+}
+function parseFindingsSummaryCounts(content) {
+    const match = content.match(/^Findings:\s*(\d+)\s+critical,\s*(\d+)\s+important,\s*(\d+)\s+medium,\s*(\d+)\s+minor\s*$/im);
+    if (!match) {
+        return null;
+    }
+    return {
+        critical: Number.parseInt(match[1] ?? '0', 10),
+        important: Number.parseInt(match[2] ?? '0', 10),
+        medium: Number.parseInt(match[3] ?? '0', 10),
+        minor: Number.parseInt(match[4] ?? '0', 10),
+    };
+}
+function parseFindingsSectionCounts(content, artifactPath) {
+    const headingMatches = [...content.matchAll(/^#{3,6}\s+(.+?)\s*#*\s*$/gm)];
+    const severityHeadings = headingMatches
+        .map((match) => ({
+        severity: normalizeHeading(match[1] ?? ''),
+        index: match.index ?? 0,
+        headingLength: match[0].length,
+    }))
+        .filter((heading) => heading.severity !== null);
+    if (severityHeadings.length === 0) {
+        return null;
+    }
+    const seenSeverities = new Set(severityHeadings.map((heading) => heading.severity));
+    const missingSeverities = SEVERITIES.filter((severity) => !seenSeverities.has(severity));
+    if (missingSeverities.length > 0) {
+        throw new Error(`Review artifact at ${artifactPath} has an incomplete Findings section; expected headings for Critical, Important, Medium, and Minor. Missing: ${missingSeverities.join(', ')}.`);
+    }
+    const counts = {
+        critical: 0,
+        important: 0,
+        medium: 0,
+        minor: 0,
+    };
+    for (const [offset, heading] of severityHeadings.entries()) {
+        const nextHeading = severityHeadings[offset + 1];
+        const sectionStart = heading.index + heading.headingLength;
+        const sectionEnd = nextHeading?.index ?? content.length;
+        counts[heading.severity] = countFindingsInSection(content.slice(sectionStart, sectionEnd));
+    }
+    return counts;
+}
+function parseFrontmatterObject(frontmatter, artifactPath) {
+    try {
+        const parsed = YAML.parse(frontmatter);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+        throw new Error('frontmatter must be a YAML object');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to parse review artifact frontmatter at ${artifactPath}: ${detail}`, { cause: error });
+    }
+}
+function hasBlockingFindings(counts) {
+    return counts.critical > 0 || counts.important > 0;
+}
+export async function parseReviewGateVerdict(artifactPath) {
+    let content;
+    try {
+        content = await readFile(artifactPath, 'utf8');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Unable to read review artifact at ${artifactPath}: ${detail}`, { cause: error });
+    }
+    const frontmatterBlock = getFrontmatterBlock(content);
+    const frontmatter = frontmatterBlock
+        ? parseFrontmatterObject(frontmatterBlock, artifactPath)
+        : {};
+    const counts = readFrontmatterCounts(frontmatter) ??
+        parseFindingsSummaryCounts(content) ??
+        parseFindingsSectionCounts(content, artifactPath);
+    if (!counts) {
+        throw new Error(`Review artifact at ${artifactPath} does not contain recognizable review findings or explicit verdict counts.`);
+    }
+    return {
+        artifactPath,
+        reviewType: normalizeReviewType(frontmatter['oat_review_type']),
+        scope: stringOrNull(frontmatter['oat_review_scope']),
+        invocation: stringOrNull(frontmatter['oat_review_invocation']),
+        counts,
+        blocking: hasBlockingFindings(counts),
+    };
+}

package/dist/config/oat-config.js

@@ -45,7 +45,7 @@ export const BUILTIN_EXEC_TARGETS = {
     },
     'cursor-default': {
         runtime: 'cursor',
-        baseCommand: ['cursor-agent', '-p', '--force'],
+        baseCommand: ['cursor-agent', '-p'],
         hostDetectionCommand: ['sh', '-c', 'test -n "$CURSOR_AGENT"'],
         availabilityCommand: ['cursor-agent', '--version'],
         priority: 70,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.35"
+    "@open-agent-toolkit/control-plane": "0.1.36"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",