@open-agent-toolkit/cli 0.1.37 → 0.1.38

package/assets/public-package-versions.json

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

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;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;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,7 +40,7 @@ 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.`;
 }
@@ -577,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');
@@ -716,6 +784,11 @@ async function runReviewGate(prompt, options, context, dependencies) {
         ]);
         const childExitCode = await executeTarget(selected, [reviewPrompt], context, dependencies);
         if (childExitCode !== 0) {
+            writeReviewGateExecutionFailure(context, {
+                target: selected.id,
+                project: projectPath,
+                exitCode: childExitCode,
+            });
             process.exitCode = childExitCode;
             return;
         }
@@ -725,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,
@@ -741,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.37",
+  "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.37"
+    "@open-agent-toolkit/control-plane": "0.1.38"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",