@open-agent-toolkit/cli 0.1.36 → 0.1.38

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

@@ -119,7 +119,10 @@ Available commands:
 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.
+`oat-project-review-receive` before the host treats it as dispositioned. Keep
+reusable lifecycle gate commands target-neutral by omitting `--target <id>`; use
+explicit target pins only for manual dispatch, debugging, or deliberately local
+overrides.
 
 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

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

@@ -270,7 +270,7 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.dispatchCeiling.preset` — `balanced`, `maximum`, or `cost-conscious`. Convenience preset that compiles to per-provider values at write time. Setting this key is the recommended way to configure the ceiling.
 - `workflow.dispatchCeiling.providers.codex` — `low`, `medium`, `high`, or `xhigh`. Concrete Codex ceiling. Set automatically when a preset is selected; also settable directly for Advanced (no preset) configurations. Provider default effort is informational for base/unpinned roles and is not treated as this ceiling.
 - `workflow.dispatchCeiling.providers.claude` — `haiku`, `sonnet`, or `opus`. Concrete Claude ceiling. Set automatically when a preset is selected; also settable directly for Advanced configurations. Claude has no separate per-dispatch effort axis, so the effort axis remains `not-applicable`.
-- `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
+- `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 
 ### Auto artifact-review preferences
 

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

@@ -112,7 +112,8 @@ JSON argv is intentional: provider commands often contain flags such as `-p` or
 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.
+defaults. Defining a trusted target makes it available to the dispatcher; it
+does not mean shared lifecycle gate commands should pin that target.
 
 Claude's default permission mode can block on
 `Skill(oat-project-review-provide)`, `oat`, `pnpm`, and shell or tool calls. A
@@ -161,7 +162,7 @@ Set or clear a skill gate:
 
 ```bash
 oat gate set oat-project-implement \
-  --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"' \
+  --command 'oat gate review --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 \
@@ -170,6 +171,11 @@ oat gate set oat-project-implement \
 oat gate unset oat-project-implement --layer user
 ```
 
+Lifecycle gate commands should normally omit `--target <id>`. Leaving the
+target unset lets the dispatcher avoid the current runtime and choose the
+highest-priority available non-host target. Pin a target only for manual
+dispatch, debugging, or a deliberate local/user-specific override.
+
 Set or clear an exec target:
 
 ```bash
@@ -186,7 +192,7 @@ oat gate target unset codex-high --layer user
 Dispatch a review through the target registry:
 
 ```bash
-oat gate review --target codex-5.5-xhigh \
+oat gate review \
   --review-type code \
   --review-scope final \
   "Use oat-project-review-provide code final to review the current project"
@@ -195,6 +201,16 @@ oat gate review --target codex-5.5-xhigh \
 Leaving `--target` unset lets target priority choose the highest-priority
 available non-host runtime.
 
+For manual or debug dispatch, use `--target <id>` to pin one target and skip
+detection/avoidance:
+
+```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 generic prompt through the target registry:
 
 ```bash
@@ -242,6 +258,7 @@ OAT does not try another target after a failed review.
 
 V1 gates avoid the current runtime, not the current model or effort setting.
 Same-runtime but different-target dispatch, such as using Cursor again with a
-different model slug, is future work. Until that exists, use `--target <id>` when
-you need an explicit reviewer target, or rely on the default `same-runtime`
-avoidance for cross-runtime review.
+different model slug, is future work. Until that exists, reusable lifecycle
+gates should rely on default `same-runtime` avoidance for cross-runtime review;
+manual and local overrides can pin an explicit reviewer target with
+`--target <id>`.

package/assets/docs/contributing/skills.md

@@ -95,9 +95,13 @@ The Gate Execution step should:
    - `prompt` - surface the failure and ask the user.
    - `warn` - record the failure and continue.
 
-For cross-runtime review gates, prefer putting
-`oat gate cross-provider-exec "<prompt>"` in the configured gate command rather
-than hard-coding a provider CLI directly in the skill. See
+For OAT review gates, prefer putting `oat gate review "<prompt>"` in the
+configured gate command rather than hard-coding a provider CLI directly in the
+skill. Use `oat gate cross-provider-exec "<prompt>"` for generic cross-runtime
+commands that should report only the child process status, not review findings.
+Reusable lifecycle gate commands should normally omit `--target <id>` so the
+dispatcher can avoid the current runtime; reserve explicit targets for
+manual/debug commands or deliberate local/user-specific overrides. See
 [Workflow Gates](../cli-utilities/workflow-gates.md) for the config and command
 surface.
 

package/assets/public-package-versions.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.22
+version: 2.0.23
 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]'
@@ -1443,7 +1443,7 @@ Before reporting this skill as complete, run the configured gate as the final st
    - `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.
+5. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands should normally omit `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
 
 ## Success Criteria
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-import-plan
-version: 1.4.1
+version: 1.4.2
 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
@@ -295,7 +295,7 @@ Before reporting this skill as complete, run the configured gate as the final st
    - `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.
+5. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands should normally omit `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
 
 ### Step 7: Output Next Action
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-plan
-version: 1.3.7
+version: 1.3.8
 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
@@ -525,7 +525,7 @@ Before reporting this skill as complete, run the configured gate as the final st
    - `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.
+5. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands should normally omit `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
 
 ## Success Criteria
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 2.1.7
+version: 2.1.8
 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
@@ -615,7 +615,7 @@ Before reporting this skill as complete, run the configured gate as the final st
    - `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.
+5. Runtime selection note (V1): the step runs the gate `command` as-is and reads no OAT runtime env var. By default, `oat gate review` and `oat gate cross-provider-exec` resolve the current host from built-in `hostDetectionCommand`s and avoid the same runtime when no exact target is supplied. Reusable lifecycle skill-gate commands should normally omit `--target <id>` so independent review stays provider-neutral. Use explicit targets only for manual/debug commands or deliberate local/user-specific overrides; do not hardcode provider/model targets in bundled skill guidance or shared lifecycle gate examples.
 
 ### Step 7: Output Next Action
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-review-provide
-version: 1.2.1
+version: 1.2.2
 description: Use when you need an ad-hoc review outside an active OAT project lifecycle. Reviews code or artifacts without project phase state, unlike oat-project-review-provide.
 argument-hint: '[unstaged|staged|base_branch=<branch>|base_sha=<sha>|<sha1>..<sha2>|--files <path1,path2,...>] [--output <path>] [--mode auto|local|tracked|inline]'
 disable-model-invocation: true
@@ -183,7 +183,7 @@ If the file already exists (same scope reviewed twice in one day), suffix with `
 
 Use the same severity model and checklist as project reviews:
 
-- Critical / Important / Minor findings
+- Critical / Important / Medium / Minor findings
 - file:line references
 - actionable fix guidance
 - verification commands

package/assets/skills/oat-review-provide/references/review-artifact-template.md

@@ -23,19 +23,25 @@ oat_review_mode: ad_hoc
 
 {2-3 sentence summary}
 
+Findings: {N} critical, {N} important, {N} medium, {N} minor
+
 ## Findings
 
 ### Critical
 
-{None or list}
+{If none: "None"}
 
 ### Important
 
-{None or list}
+{If none: "None"}
+
+### Medium
+
+{If none: "None"}
 
 ### Minor
 
-{None or list}
+{If none: "None"}
 
 ## Verification Commands
 

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":"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"}
+{"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;AAQpC,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;AAyZD,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;AAo6BD,wBAAgB,iBAAiB,CAC/B,SAAS,GAAE,OAAO,CAAC,uBAAuB,CAAM,GAC/C,OAAO,CAwKT"}

package/dist/commands/gate/index.js

@@ -10,7 +10,7 @@ import { resolveEffectiveConfig, resolveExecTargets, resolveGate, } from '../../
 import { dirExists, fileExists } from '../../fs/io.js';
 import { normalizeToPosixPath, resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
-import { parseReviewGateVerdict, } from './review-verdict.js';
+import { parseReviewGateVerdict, severityDisplayName, } from './review-verdict.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
@@ -40,10 +40,16 @@ const VALID_REVIEW_GATE_THRESHOLDS = [
     '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.';
+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. Write a canonical review artifact with `### Critical`, `### Important`, `### Medium`, and `### Minor` headings in that order, using `None` for empty sections.';
 function reviewGateProjectContext(projectPath) {
     return `Resolved OAT project path: ${projectPath}. Run the review for this project path.`;
 }
+function assembleReviewGatePrompt(segments) {
+    return segments
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0)
+        .join('\n\n');
+}
 async function runChildProcess(command, args, options) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, {
@@ -571,15 +577,83 @@ function reviewBlocksAtThreshold(verdict, threshold) {
     }
     return verdict.counts.minor > 0;
 }
+function buildReviewGateHandoff(options) {
+    const receiveInstruction = `Run oat-project-review-receive for ${options.artifactPath} before treating this gate review as consumed.`;
+    const thresholdIndex = VALID_REVIEW_GATE_THRESHOLDS.indexOf(options.threshold);
+    const nonBlockingSeverities = VALID_REVIEW_GATE_THRESHOLDS.slice(thresholdIndex + 1).filter((severity) => options.verdict.counts[severity] > 0);
+    const hasFinalNonBlockingFindings = options.verdict.scope === 'final' &&
+        !options.blocking &&
+        nonBlockingSeverities.length > 0;
+    if (!hasFinalNonBlockingFindings) {
+        return receiveInstruction;
+    }
+    const counts = nonBlockingSeverities
+        .map((severity) => `${severity}=${options.verdict.counts[severity]}`)
+        .join(', ');
+    return `Gate passed at the ${options.threshold} threshold, but the final review still contains non-blocking findings (${counts}). Run oat-project-review-receive for ${options.artifactPath} to disposition them before marking the final review row passed.`;
+}
+function reviewGateOutcome(payload) {
+    if (payload.blocking) {
+        return 'review_completed_blocking_findings';
+    }
+    if (payload.normalization) {
+        return 'review_completed_artifact_normalized_gate_passed';
+    }
+    return 'review_completed_gate_passed';
+}
 function writeReviewGateResult(context, payload) {
+    const outcome = reviewGateOutcome(payload);
     if (context.json) {
-        context.logger.json(payload);
+        context.logger.json({ outcome, ...payload });
         return;
     }
+    if (outcome === 'review_completed_blocking_findings') {
+        context.logger.info('Review completed and found blocking issues.');
+    }
+    else if (outcome === 'review_completed_artifact_normalized_gate_passed') {
+        context.logger.info('Review completed, artifact was normalized, and gate passed.');
+    }
+    else {
+        context.logger.info('Review completed and gate passed.');
+    }
     context.logger.info(`Review artifact: ${payload.artifactPath}`);
+    if (payload.normalization) {
+        context.logger.info(`Artifact normalized: inserted ${payload.normalization.insertedSeverities.map((severity) => severityDisplayName(severity)).join(', ')} empty Findings section(s).`);
+    }
     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);
 }
+function writeReviewGateExecutionFailure(context, payload) {
+    const message = `Review did not complete: target ${payload.target} exited with code ${payload.exitCode}.`;
+    if (context.json) {
+        context.logger.json({
+            status: 'review_failed',
+            outcome: 'review_did_not_complete',
+            target: payload.target,
+            project: payload.project,
+            exitCode: payload.exitCode,
+            message,
+        });
+        return;
+    }
+    context.logger.error(message);
+}
+function writeReviewGateArtifactValidationFailure(context, payload) {
+    if (context.json) {
+        context.logger.json({
+            status: 'artifact_validation_failed',
+            outcome: 'review_completed_artifact_validation_failed',
+            target: payload.target,
+            project: payload.project,
+            artifactPath: payload.artifactPath,
+            message: payload.message,
+            recovery: payload.recovery,
+        });
+        return;
+    }
+    context.logger.error(`Review completed but artifact validation failed: ${payload.message}`);
+    context.logger.error(payload.recovery);
+}
 async function updateConfigLayer(context, layer, dependencies, mutate) {
     const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
     const userConfigDir = join(context.home, '.oat');
@@ -697,7 +771,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             repoRoot,
             projectPath,
         });
-        const reviewPrompt = [
+        const reviewPrompt = assembleReviewGatePrompt([
             REVIEW_GATE_CONTEXT_NOTE,
             reviewGateProjectContext(projectPath),
             ...(options.reviewType?.trim()
@@ -706,10 +780,15 @@ async function runReviewGate(prompt, options, context, dependencies) {
             ...(options.reviewScope?.trim()
                 ? [`Review scope: ${options.reviewScope.trim()}.`]
                 : []),
-            ...prompt,
-        ];
-        const childExitCode = await executeTarget(selected, reviewPrompt, context, dependencies);
+            prompt.join(' '),
+        ]);
+        const childExitCode = await executeTarget(selected, [reviewPrompt], context, dependencies);
         if (childExitCode !== 0) {
+            writeReviewGateExecutionFailure(context, {
+                target: selected.id,
+                project: projectPath,
+                exitCode: childExitCode,
+            });
             process.exitCode = childExitCode;
             return;
         }
@@ -719,11 +798,41 @@ async function runReviewGate(prompt, options, context, dependencies) {
         });
         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.`);
+            writeReviewGateArtifactValidationFailure(context, {
+                target: selected.id,
+                project: projectPath,
+                artifactPath: null,
+                message: `No new review artifact was detected for project ${projectPath}.`,
+                recovery: 'Ensure the review provider wrote a project review artifact. If it did, fix or attach that artifact and run oat-project-review-receive before treating the review as consumed.',
+            });
+            process.exitCode = 1;
+            return;
+        }
+        let verdict;
+        try {
+            verdict = await parseReviewGateVerdict(join(repoRoot, producedArtifact.path), {
+                normalizeMissingEmptySeveritySections: true,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            writeReviewGateArtifactValidationFailure(context, {
+                target: selected.id,
+                project: projectPath,
+                artifactPath: producedArtifact.path,
+                message: detail,
+                recovery: `The review artifact was created at ${producedArtifact.path} but could not be consumed. Fix the artifact format, then run oat-project-review-receive for ${producedArtifact.path}; if the only issue is a missing zero-count severity heading, rerun the gate to normalize the same artifact instead of creating a new review version.`,
+            });
+            process.exitCode = 1;
+            return;
         }
-        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.`;
+        const handoff = buildReviewGateHandoff({
+            artifactPath: producedArtifact.path,
+            verdict,
+            threshold,
+            blocking,
+        });
         writeReviewGateResult(context, {
             status: blocking ? 'blocked' : 'ok',
             target: selected.id,
@@ -735,6 +844,7 @@ async function runReviewGate(prompt, options, context, dependencies) {
             reviewType: verdict.reviewType,
             scope: verdict.scope,
             invocation: verdict.invocation,
+            normalization: verdict.normalization,
             handoff,
         });
         process.exitCode = blocking ? 1 : 0;

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

@@ -10,6 +10,14 @@ export interface ReviewGateVerdict {
         minor: number;
     };
     blocking: boolean;
+    normalization?: {
+        insertedSeverities: Severity[];
+    };
+}
+export type Severity = keyof ReviewGateVerdict['counts'];
+export interface ParseReviewGateVerdictOptions {
+    normalizeMissingEmptySeveritySections?: boolean;
 }
-export declare function parseReviewGateVerdict(artifactPath: string): Promise<ReviewGateVerdict>;
+export declare function severityDisplayName(severity: Severity): string;
+export declare function parseReviewGateVerdict(artifactPath: string, options?: ParseReviewGateVerdictOptions): Promise<ReviewGateVerdict>;
 //# sourceMappingURL=review-verdict.d.ts.map

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

@@ -1 +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"}
+{"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;IAClB,aAAa,CAAC,EAAE;QACd,kBAAkB,EAAE,QAAQ,EAAE,CAAC;KAChC,CAAC;CACH;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC5C,qCAAqC,CAAC,EAAE,OAAO,CAAC;CACjD;AAqID,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE9D;AAqRD,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAsD5B"}

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

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import YAML from 'yaml';
 const SEVERITIES = [
@@ -89,6 +89,89 @@ function normalizeHeading(value) {
     }
     return null;
 }
+export function severityDisplayName(severity) {
+    return severity.charAt(0).toUpperCase() + severity.slice(1);
+}
+function markdownLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        const newlineIndex = content.indexOf('\n', start);
+        const end = newlineIndex === -1 ? content.length : newlineIndex;
+        lines.push({
+            text: content.slice(start, end),
+            start,
+        });
+        start = newlineIndex === -1 ? content.length : newlineIndex + 1;
+    }
+    return lines;
+}
+function fenceMarker(line) {
+    const match = line.match(/^\s*(`{3,}|~{3,})/);
+    if (!match?.[1]) {
+        return null;
+    }
+    return {
+        marker: match[1].startsWith('`') ? '`' : '~',
+        length: match[1].length,
+    };
+}
+function linesOutsideFences(content) {
+    const outsideFenceLines = [];
+    let activeFence = null;
+    for (const line of markdownLines(content)) {
+        const marker = fenceMarker(line.text);
+        if (marker) {
+            if (!activeFence) {
+                activeFence = marker;
+            }
+            else if (marker.marker === activeFence.marker &&
+                marker.length >= activeFence.length) {
+                activeFence = null;
+            }
+            continue;
+        }
+        if (!activeFence) {
+            outsideFenceLines.push(line);
+        }
+    }
+    return outsideFenceLines;
+}
+function findFindingsSection(content) {
+    const lines = linesOutsideFences(content);
+    const findingsHeading = lines.find((line) => /^##\s+Findings\s*#*\s*$/i.test(line.text));
+    if (!findingsHeading) {
+        return null;
+    }
+    const start = findingsHeading.start + findingsHeading.text.length;
+    const nextPeerHeading = lines.find((line) => line.start > findingsHeading.start &&
+        /^#{1,2}\s+.+?\s*#*\s*$/.test(line.text));
+    const end = nextPeerHeading?.start ?? content.length;
+    return {
+        start,
+        end,
+        content: content.slice(start, end),
+    };
+}
+function findSeverityHeadings(content) {
+    const findingsSection = findFindingsSection(content);
+    const scanContent = findingsSection?.content ?? content;
+    const offset = findingsSection?.start ?? 0;
+    return linesOutsideFences(scanContent)
+        .map((line) => {
+        const match = line.text.match(/^#{3,6}\s+(.+?)\s*#*\s*$/);
+        return {
+            severity: normalizeHeading(match?.[1] ?? ''),
+            index: offset + line.start,
+            headingLength: line.text.length,
+        };
+    })
+        .filter((heading) => heading.severity !== null);
+}
+function missingSeverityHeadings(severityHeadings) {
+    const seenSeverities = new Set(severityHeadings.map((heading) => heading.severity));
+    return SEVERITIES.filter((severity) => !seenSeverities.has(severity));
+}
 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) {
@@ -102,19 +185,12 @@ function parseFindingsSummaryCounts(content) {
     };
 }
 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);
+    const findingsSection = findFindingsSection(content);
+    const severityHeadings = findSeverityHeadings(content);
     if (severityHeadings.length === 0) {
         return null;
     }
-    const seenSeverities = new Set(severityHeadings.map((heading) => heading.severity));
-    const missingSeverities = SEVERITIES.filter((severity) => !seenSeverities.has(severity));
+    const missingSeverities = missingSeverityHeadings(severityHeadings);
     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(', ')}.`);
     }
@@ -127,7 +203,7 @@ function parseFindingsSectionCounts(content, artifactPath) {
     for (const [offset, heading] of severityHeadings.entries()) {
         const nextHeading = severityHeadings[offset + 1];
         const sectionStart = heading.index + heading.headingLength;
-        const sectionEnd = nextHeading?.index ?? content.length;
+        const sectionEnd = nextHeading?.index ?? findingsSection?.end ?? content.length;
         counts[heading.severity] = countFindingsInSection(content.slice(sectionStart, sectionEnd));
     }
     return counts;
@@ -150,7 +226,54 @@ function parseFrontmatterObject(frontmatter, artifactPath) {
 function hasBlockingFindings(counts) {
     return counts.critical > 0 || counts.important > 0;
 }
-export async function parseReviewGateVerdict(artifactPath) {
+function insertionTextForSeverity(severity) {
+    return `\n### ${severityDisplayName(severity)}\n\nNone\n`;
+}
+function insertionPointForMissingSeverity(content, missingSeverity) {
+    const findingsSection = findFindingsSection(content);
+    const sectionEnd = findingsSection?.end ?? content.length;
+    const severityHeadings = findSeverityHeadings(content);
+    const missingSeverityRank = SEVERITIES.indexOf(missingSeverity);
+    const nextHeading = severityHeadings.find((heading) => SEVERITIES.indexOf(heading.severity) > missingSeverityRank);
+    return nextHeading?.index ?? sectionEnd;
+}
+function insertMissingSeveritySection(content, severity) {
+    const insertionPoint = insertionPointForMissingSeverity(content, severity);
+    const insertion = insertionTextForSeverity(severity);
+    const suffix = content.slice(insertionPoint);
+    const needsTrailingBlank = suffix.length > 0 ? '\n' : '';
+    return `${content.slice(0, insertionPoint)}${insertion}${needsTrailingBlank}${suffix}`;
+}
+async function normalizeMissingEmptySeveritySections(artifactPath, content, counts) {
+    if (!findFindingsSection(content)) {
+        throw new Error(`Review artifact at ${artifactPath} does not contain a ## Findings section, so missing severity headings cannot be safely normalized.`);
+    }
+    let normalizedContent = content;
+    const insertedSeverities = [];
+    for (const severity of missingSeverityHeadings(findSeverityHeadings(content))) {
+        if (counts[severity] !== 0) {
+            throw new Error(`Review artifact at ${artifactPath} is missing the ${severityDisplayName(severity)} Findings section, but structured counts report ${counts[severity]} ${severity} finding(s). This cannot be safely normalized.`);
+        }
+        normalizedContent = insertMissingSeveritySection(normalizedContent, severity);
+        insertedSeverities.push(severity);
+    }
+    if (insertedSeverities.length > 0) {
+        await writeFile(artifactPath, normalizedContent, 'utf8');
+    }
+    return { content: normalizedContent, insertedSeverities };
+}
+function resolveCounts(content, frontmatter) {
+    const frontmatterCounts = readFrontmatterCounts(frontmatter);
+    if (frontmatterCounts) {
+        return frontmatterCounts;
+    }
+    const summaryCounts = parseFindingsSummaryCounts(content);
+    if (summaryCounts) {
+        return summaryCounts;
+    }
+    return null;
+}
+export async function parseReviewGateVerdict(artifactPath, options = {}) {
     let content;
     try {
         content = await readFile(artifactPath, 'utf8');
@@ -163,9 +286,16 @@ export async function parseReviewGateVerdict(artifactPath) {
     const frontmatter = frontmatterBlock
         ? parseFrontmatterObject(frontmatterBlock, artifactPath)
         : {};
-    const counts = readFrontmatterCounts(frontmatter) ??
-        parseFindingsSummaryCounts(content) ??
-        parseFindingsSectionCounts(content, artifactPath);
+    let counts = resolveCounts(content, frontmatter);
+    let insertedSeverities = [];
+    if (counts && options.normalizeMissingEmptySeveritySections) {
+        const normalized = await normalizeMissingEmptySeveritySections(artifactPath, content, counts);
+        content = normalized.content;
+        insertedSeverities = normalized.insertedSeverities;
+    }
+    if (!counts) {
+        counts = parseFindingsSectionCounts(content, artifactPath);
+    }
     if (!counts) {
         throw new Error(`Review artifact at ${artifactPath} does not contain recognizable review findings or explicit verdict counts.`);
     }
@@ -176,5 +306,12 @@ export async function parseReviewGateVerdict(artifactPath) {
         invocation: stringOrNull(frontmatter['oat_review_invocation']),
         counts,
         blocking: hasBlockingFindings(counts),
+        ...(insertedSeverities.length > 0
+            ? {
+                normalization: {
+                    insertedSeverities,
+                },
+            }
+            : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "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.36"
+    "@open-agent-toolkit/control-plane": "0.1.38"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",