orchestrator-workflow 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.36.0] - 2026-09-16
+
+- A `validate-review-report <file>` CLI subcommand (`-` reads stdin) checks a
+  reviewer return's YAML against the reviewer output contract's required
+  fields and enums, printing one diagnostic per missing or invalid field and
+  exiting `0`/`1`/`2` for valid/structurally-invalid/usage-error; `--format
+  json` prints the same diagnostics as one JSON object. The check is
+  structural only, never semantic, and never constitutes orchestrator
+  acceptance. Its schema lives in `src/review-report.ts` and is pinned in
+  `test/docs-consistency.test.ts` against the contract block in
+  `assets/agents/reviewer.md` itself, so a contract edit without a matching
+  schema edit fails the suite instead of drifting silently. An excess
+  positional argument (e.g. two file paths) now also exits `2` as a usage
+  error instead of silently validating only the first path. A fenced
+  return ends at the first closing fence that starts at column 0, so a
+  triple-backtick sequence inside a value (a reviewer quoting a fenced
+  snippet in a `description`) no longer closes the block early and hands
+  the parser a truncated document.
+- Removed incidental blank-line padding (a run of seven consecutive blank
+  lines) and a mid-sentence paragraph split from
+  `docs/okf/subagent-contracts-superset.md`'s mutation-probe field
+  discussion, and corrected its Commits field section, which still said
+  the not-applicable `commits: []` clause is pinned "in both copies"
+  after the 0.35.0 contract-reduction refactor left it in the installed
+  implementer prompt alone. Re-pointed every citation the removed lines
+  shifted (two `docs/okf/log.md` self-citations into this doc, and the
+  `SIBLING_GUARD_BUNDLE_ALLOWLIST` explanation comment in
+  `test/docs-consistency.test.ts`, whose recorded `:1217`/`:1232`
+  coordinates no longer matched the paragraph's current citations).
+  Docs-only: no YAML contract, role prompt, guard matcher, or exemption
+  geometry changed. Anchored by agent-dx tracker task 8a55e082.
+
+- `assets/agents/implementer.md` gains a pre-return rule bullet next to
+  the commit-reporting ones: before committing, when slop-detector is
+  available run `slop-detector check <changed file> [<changed file> ...]
+  --pack review-slop` over every changed file and `git log -1
+  --format=%B | slop-detector check --stdin-path COMMIT_MSG --pack
+  review-slop` over the commit message, with the repository-vendored
+  `node packages/slop-detector/dist/cli.js check ...` path named as the
+  alternative where the CLI is not installed on PATH; fix every
+  block-level finding before returning, or add a legitimate match to
+  `review.allow`. Only exit `0` or `1` is a result: exit `2` is a usage
+  error, not a clean check. A returned report that skipped the check on a
+  diff with block-level findings is a misfire, not evidence. Pinned by
+  `test/docs-consistency.test.ts`;
+  `docs/okf/subagent-contracts-superset.md` gained a matching sentence
+  describing the rule.
+  - Anchored by pandora batch 51 (`.ai/runs/2026-09-13-quickwins-batch51`):
+    four review rounds (or post-merge cleanup commits) across five repos
+    were spent catching run-local review tokens (finding ids, round
+    references, workspace-handoff phrases) that nothing mechanical
+    flagged before `slop-detector`'s new `review-slop` pack existed; see
+    that package's own CHANGELOG.md for the pack itself and the
+    pre-cleanup PR the fixtures were drawn from.
+
 ## [0.35.0] - 2026-09-15
 
 - The npm tarball now ships a `LICENSE` file matching the repo root LICENSE

package/README.md

@@ -691,3 +691,41 @@ references.
 package's version, so a release of `okf-kit` must bump those pins in the
 same commit as the version cut; see `CONTRIBUTING.md`'s "Releasing okf-kit"
 section (repo root) for the order.
+
+## Reviewer-report validation
+
+```bash
+orchestrator-workflow validate-review-report path/to/return.yaml
+orchestrator-workflow validate-review-report - < path/to/return.yaml
+orchestrator-workflow validate-review-report path/to/return.yaml --format json
+```
+
+Checks a reviewer return's YAML against the reviewer output contract's
+required fields and enums (see the "Reviewer output contract" section of
+`assets/skill/references/contracts.md`, byte-identical to the contract in
+`assets/agents/reviewer.md`), whether the return is fenced in a code
+block (any language tag, or none) or given unfenced, and prints one
+diagnostic per missing or invalid field. A fenced return ends at the
+first closing fence that starts at column 0, so a reviewer quoting a
+fenced snippet inside a value (a `description` block scalar, which YAML
+indents) does not truncate the return. `--format json` prints the same
+diagnostics as a single JSON object instead of human-readable text. It
+exits `0` when the return is structurally valid, `1` when it is
+structurally invalid (a required field is missing or its value falls
+outside its enum, or the input is unparsable, empty, or not a mapping),
+and `2` for a usage error (an unreadable file, an unrecognized `--format`
+value, a missing `<file>` argument, an unknown option, or an excess
+positional argument).
+`--format json` governs the validation verdict only: a commander parsing
+error (missing argument, unknown option, excess arguments) or an
+unrecognized `--format` value itself still prints plain text to stderr
+with nothing on stdout, regardless of `--format`; the one exception is an
+unreadable file, which does emit the JSON envelope on stdout. This check
+is structural only: it never judges semantic adequacy, cannot waive a
+finding, and passing it is never orchestrator acceptance. The
+required-field set it checks is hand-maintained in `src/review-report.ts`
+and pinned against the contract block itself by
+`test/docs-consistency.test.ts`, so a contract edit without a matching
+schema edit fails the suite instead of drifting silently; every field
+listed there is dispatched to its own checker, so an entry added to the
+list without a checker fails to typecheck rather than passing unchecked.

package/assets/agents/implementer.md

@@ -133,6 +133,19 @@ Rules:
   than omitting the field.
 - Populate a non-empty `commits` field by pasting `git log --reverse
   --format=%H <base>..HEAD`; never type or hand-complete commit shas.
+- Before committing, when slop-detector is available run `slop-detector
+  check <changed file> [<changed file> ...] --pack review-slop` over every
+  changed file, and `git log -1 --format=%B | slop-detector check
+  --stdin-path COMMIT_MSG --pack review-slop` over the commit message;
+  where it is vendored in the repository rather than installed on PATH,
+  the same two invocations run as `node
+  packages/slop-detector/dist/cli.js check ...`. Fix every block-level
+  finding before returning, or add a legitimate match to `review.allow`
+  in the repository's slop.config.yml rather than deleting correct text.
+  Only exit `0` or `1` is a result; exit `2` is a usage error (a mistyped
+  invocation, or `--stdin-path` with nothing piped in), so it is not a
+  clean check. A returned report that skipped this check on a diff with
+  block-level findings is a misfire, not evidence.
 - Verification plans, probe plans, and repeat tallies run in the foreground,
   and the implementer reports their returns in the same turn as the last
   check. A background monitor is no substitute for those returns.

package/assets/skill/references/contracts.md

@@ -165,6 +165,24 @@ withdrawn:
 When it is missing, the orchestrator asks the reviewer to resupply it
 instead of inferring one from the findings list.
 
+A structural check for this exact contract ships as a CLI subcommand:
+`orchestrator-workflow validate-review-report <file>` (pass `-` to read the
+return from stdin instead) parses the reviewer return's YAML, fenced in a
+code block with any language tag or none, or unfenced, and checks the
+required fields and enums above one by one, printing a diagnostic (path,
+expected, got) for each missing or invalid field; add `--format json` for
+the same diagnostics as a single JSON object. It exits `0` when the return
+is structurally valid, `1` when it is structurally invalid (a missing or
+out-of-enum required field, or unparsable, empty, non-mapping input), and
+`2` for a usage error (an unreadable file, an unrecognized `--format`
+value, or an argument-parsing error: a missing `<file>` argument, an
+unknown option, an excess positional argument). `--format json` governs
+the validation verdict only: an argument-parsing error or an unrecognized
+`--format` value still prints plain text to stderr, except an unreadable
+file, which still emits the JSON envelope on stdout. The check is
+structural only: it never judges semantic adequacy, cannot waive a
+finding, and passing it is never orchestrator acceptance.
+
 `recurrence` classifies each finding against earlier rounds on the same
 task: `new` for a defect class not previously found here, `repeated` for
 one that already appeared in an earlier round. On a task's first review

package/dist/cli.js

@@ -1172,6 +1172,101 @@ program
     printTargetDetail(targetReport, PACKAGE_VERSION);
     process.exitCode = exitCode;
 });
+const validateReviewReportCommand = program
+    .command("validate-review-report")
+    .description("Check a reviewer return's YAML against the reviewer output contract's required fields and enums; reports structural validity ONLY, never semantic adequacy, and never waives a finding or constitutes orchestrator acceptance")
+    .argument("<file>", "path to a file holding the reviewer return's YAML, or - to read stdin")
+    .option("--format <format>", "output format: text (default) or json", "text")
+    // commander 12's default for a subcommand is `allowExcessArguments:
+    // true`, so `validate-review-report a.yaml extra.yaml` silently
+    // validated only `a.yaml` and exited 0 (fix-round, review finding M1).
+    // Disabling it turns a trailing extra argument into commander's own
+    // "too many arguments" parsing error, which the scoped `exitOverride`
+    // below then maps to exit 2 like every other usage error.
+    .allowExcessArguments(false)
+    .action(async (file, opts) => {
+    // Imported dynamically, here rather than as a top-level static import,
+    // so this command's addition cannot shift the line numbers of any
+    // statement above it in this file: several docs/okf/ citations anchor
+    // to exact lines in src/cli.ts, and a top-level import would have
+    // re-pointed all of them for a reason unrelated to their own content.
+    const { STRUCTURAL_ONLY_NOTE, validateReviewReport } = await import("./review-report.js");
+    const format = opts.format ?? "text";
+    if (format !== "text" && format !== "json") {
+        console.error(`Unknown --format value: ${format} (expected "text" or "json")`);
+        console.error(STRUCTURAL_ONLY_NOTE);
+        process.exitCode = 2;
+        return;
+    }
+    let raw;
+    try {
+        raw = readFileSync(file === "-" ? 0 : file, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const label = file === "-" ? "stdin" : file;
+        if (format === "json") {
+            console.log(JSON.stringify({
+                valid: false,
+                diagnostics: [
+                    { path: "<file>", expected: "a readable file", got: message },
+                ],
+                warnings: [],
+                note: STRUCTURAL_ONLY_NOTE,
+            }));
+        }
+        else {
+            console.error(`Could not read ${label}: ${message}`);
+            console.error(STRUCTURAL_ONLY_NOTE);
+        }
+        process.exitCode = 2;
+        return;
+    }
+    const result = validateReviewReport(raw);
+    if (format === "json") {
+        console.log(JSON.stringify({
+            valid: result.valid,
+            diagnostics: result.diagnostics,
+            warnings: result.warnings,
+            note: STRUCTURAL_ONLY_NOTE,
+        }));
+        process.exitCode = result.valid ? 0 : 1;
+        return;
+    }
+    for (const warning of result.warnings) {
+        console.error(`warning: ${warning}`);
+    }
+    // Both the exit-0 (valid) and exit-1 (invalid) cases are "verdict
+    // paths": a validation verdict was actually computed, so its message
+    // and the structural-only note that qualifies it belong on the same
+    // stream. Previously the note printed on stderr unconditionally while
+    // the valid-case verdict printed on stdout, splitting one reading
+    // across two streams (fix-round, review finding L5); the two exit-2
+    // "usage error" branches above keep stderr for both, since no verdict
+    // was computed there.
+    if (result.valid) {
+        console.log("Structurally valid reviewer return.");
+    }
+    else {
+        console.log(`Structurally invalid reviewer return (${result.diagnostics.length} issue${result.diagnostics.length === 1 ? "" : "s"}):`);
+        for (const diagnostic of result.diagnostics) {
+            console.log(`  ${diagnostic.path}: expected ${diagnostic.expected}, got ${diagnostic.got}`);
+        }
+    }
+    console.log(STRUCTURAL_ONLY_NOTE);
+    process.exitCode = result.valid ? 0 : 1;
+});
+// Commander's default for a parsing failure (a missing `<file>` argument,
+// an unknown option, excess arguments) is exit code 1, the same code this
+// command otherwise reserves for "structurally invalid" -- collapsing
+// "you didn't invoke this right" into "the return you gave me is invalid"
+// (fix-round, review finding L1). Scoped to this one subcommand so every
+// other command's existing commander-parsing exit behavior is untouched:
+// commander already prints the error message itself before calling this
+// callback, so remapping the exit code is all that is needed here.
+validateReviewReportCommand.exitOverride((err) => {
+    process.exit(err.exitCode === 0 ? 0 : 2);
+});
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exitCode = 1;

package/dist/review-report.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Structural schema for the reviewer output contract (the final ```yaml
+ * block in `assets/agents/reviewer.md`, mirrored byte-for-byte in
+ * `assets/skill/references/contracts.md`). This module is the single
+ * hand-maintained copy of that shape in code; `test/docs-consistency.test.ts`
+ * parses the contract block itself and asserts it matches the constants
+ * below exactly, so a contract edit without a matching edit here fails the
+ * suite instead of drifting silently.
+ *
+ * This validator checks structure only. It never judges semantic adequacy,
+ * never waives a finding, and its passing is never orchestrator acceptance.
+ */
+/** Top-level field names, in the contract's own order. */
+export declare const TOP_LEVEL_FIELDS: readonly ["status", "role", "task_id", "summary", "findings", "acceptance_recommendation", "missing_tests", "residual_risks", "reproduction", "method_applied", "withdrawn"];
+/** Field names of one `findings[]` entry, in the contract's own order. */
+export declare const FINDING_FIELDS: readonly ["severity", "category", "description", "suggested_fix", "recurrence", "introduced_by_delta"];
+/** Field names of the `reproduction` object, in the contract's own order. */
+export declare const REPRODUCTION_FIELDS: readonly ["method", "sample_size", "result", "matches_implementer_claim"];
+/** Field names of one `withdrawn[]` entry, in the contract's own order. */
+export declare const WITHDRAWN_FIELDS: readonly ["description", "reason"];
+/**
+ * Enum spellings keyed by their bare field name. Every enum-bearing field
+ * in the contract has a name unique across the whole block, so a flat map
+ * (rather than one keyed by full path) is enough and matches how the
+ * contract text itself reads (`key: a | b | c`).
+ */
+export declare const ENUM_VALUES: Readonly<Record<string, readonly string[]>>;
+export interface Diagnostic {
+    /** Dotted/bracketed location of the offending field, e.g. `findings[0].severity`. */
+    path: string;
+    /** What the schema requires at that path. */
+    expected: string;
+    /** What was actually found (or "missing"). */
+    got: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    diagnostics: Diagnostic[];
+    /** Non-fatal observations, e.g. prose found after the fenced block. */
+    warnings: string[];
+}
+/**
+ * This validator reports structural validity only. It does not judge
+ * semantic adequacy, cannot waive findings, and passing it does not
+ * constitute orchestrator acceptance.
+ */
+export declare const STRUCTURAL_ONLY_NOTE = "Structural check only: this does not judge semantic adequacy, cannot waive findings, and does not constitute orchestrator acceptance.";
+/** Every field name any of the four contract constants declares. */
+export type SchemaFieldName = (typeof TOP_LEVEL_FIELDS)[number] | (typeof FINDING_FIELDS)[number] | (typeof REPRODUCTION_FIELDS)[number] | (typeof WITHDRAWN_FIELDS)[number];
+/**
+ * The structural kind of one contract field: which input classes its
+ * checker accepts and which it rejects. Declared once, next to the
+ * dispatch tables above, and read by both this module (for the `expected`
+ * text a diagnostic carries) and `test/review-report.test.ts`'s case
+ * generator, which derives its whole case list from these kinds rather
+ * than from a hand-enumerated list of checks.
+ *
+ * - `enum`: present, a string, and one of `ENUM_VALUES[field]`.
+ * - `string`: present and a string; the empty string is accepted.
+ * - `non-empty-string`: present, a string, and not blank.
+ * - `scalar`: present and either a string or a number.
+ * - `array`: present and an array; an empty array is accepted.
+ * - `mapping-list`: `array`, and every element a mapping.
+ * - `mapping`: present and a mapping.
+ *
+ * A new kind is declared here, in {@link KIND_EXPECTED}, and in the
+ * generator's own `Record<FieldKind, ...>` value tables; each of those is
+ * keyed by this type, so a kind with no expectation text or no input
+ * classes is a compile error rather than an untested kind.
+ */
+export type FieldKind = "enum" | "string" | "non-empty-string" | "scalar" | "array" | "mapping-list" | "mapping";
+/**
+ * The declared kind of every field of every contract constant, keyed by
+ * bare field name the way {@link ENUM_VALUES} is: a name is unique across
+ * the whole contract block except for `description`, which `findings[]`
+ * and `withdrawn[]` share with the same kind. The `satisfies
+ * Record<SchemaFieldName, FieldKind>` clause means a name added to any of
+ * the four constants without a kind here is a TypeScript compile error,
+ * the same way it is already an error to add one without a checker in the
+ * dispatch tables above. Were a future contract to reuse one name at two
+ * levels with two different kinds, this flat map could hold only one of
+ * them: the generator asserts each field's real diagnostics against its
+ * declared kind, so that shows up as a failing generated case rather than
+ * as an unchecked field.
+ */
+export declare const FIELD_KINDS: {
+    status: "enum";
+    role: "enum";
+    task_id: "non-empty-string";
+    summary: "array";
+    findings: "mapping-list";
+    acceptance_recommendation: "enum";
+    missing_tests: "array";
+    residual_risks: "array";
+    reproduction: "mapping";
+    method_applied: "enum";
+    withdrawn: "mapping-list";
+    severity: "enum";
+    category: "enum";
+    description: "string";
+    suggested_fix: "string";
+    recurrence: "enum";
+    introduced_by_delta: "enum";
+    method: "scalar";
+    sample_size: "scalar";
+    result: "scalar";
+    matches_implementer_claim: "enum";
+    reason: "string";
+};
+/**
+ * The `expected` text this validator's diagnostics about `field` carry.
+ * The checkers above hold that text literally, at their own push sites;
+ * this is the schema's declaration of the same text, which the generated
+ * test cases assert the checkers actually produce, so a checker whose
+ * behaviour stops matching its declared kind fails a case instead of
+ * drifting quietly.
+ */
+export declare function expectedTextFor(field: SchemaFieldName): string;
+/** The `expected` text a diagnostic about one element of a `mapping-list` carries. */
+export declare const MAPPING_LIST_ELEMENT_EXPECTED: string;
+interface ExtractedYaml {
+    yamlText: string;
+    warnings: string[];
+}
+/**
+ * A reviewer return is commonly wrapped in a single fenced code block.
+ * Strips one leading/trailing fence when present, whatever language tag
+ * it carries (```yaml, ```yml, a bare ``` , or any other tag -- a
+ * language-less fence previously fell through to the "literal YAML"
+ * branch below and produced a confusing YAML parse error instead of a
+ * clean structural diagnostic; fix-round, review finding L2); anything
+ * unfenced is treated as literal YAML. The fence is located anywhere in
+ * the input, not only at its very start: a return prefixed with prose
+ * ("Here is my report:\n```yaml ...") previously fell through to the
+ * "literal YAML" branch, since the fence pattern was anchored to the
+ * start of the string, and produced a raw parse error instead of a
+ * structural diagnostic (fix-round, review finding L1). Prose found
+ * before the opening fence or after the closing fence is tolerated, but
+ * each is named as its own warning rather than silently dropped.
+ *
+ * The closing fence must start at column 0: the pattern anchors it with
+ * `^` under the `m` flag, so a triple-backtick sequence inside a value
+ * (a reviewer quoting a fenced snippet in a `description` block scalar,
+ * which YAML necessarily indents) can no longer close the block early
+ * and hand the parser a truncated document, which surfaced as
+ * diagnostics about fields the return actually carried (fix-round,
+ * review finding L3).
+ */
+export declare function extractYamlSource(raw: string): ExtractedYaml;
+/**
+ * Validates a reviewer return against the reviewer output contract's
+ * structure. Reports structural validity ONLY: it never judges semantic
+ * adequacy, never waives a finding, and passing it is never orchestrator
+ * acceptance.
+ */
+export declare function validateReviewReport(raw: string): ValidationResult;
+export {};

package/dist/review-report.js

@@ -0,0 +1,449 @@
+import { parse as parseYaml } from "yaml";
+/**
+ * Structural schema for the reviewer output contract (the final ```yaml
+ * block in `assets/agents/reviewer.md`, mirrored byte-for-byte in
+ * `assets/skill/references/contracts.md`). This module is the single
+ * hand-maintained copy of that shape in code; `test/docs-consistency.test.ts`
+ * parses the contract block itself and asserts it matches the constants
+ * below exactly, so a contract edit without a matching edit here fails the
+ * suite instead of drifting silently.
+ *
+ * This validator checks structure only. It never judges semantic adequacy,
+ * never waives a finding, and its passing is never orchestrator acceptance.
+ */
+/** Top-level field names, in the contract's own order. */
+export const TOP_LEVEL_FIELDS = [
+    "status",
+    "role",
+    "task_id",
+    "summary",
+    "findings",
+    "acceptance_recommendation",
+    "missing_tests",
+    "residual_risks",
+    "reproduction",
+    "method_applied",
+    "withdrawn",
+];
+/** Field names of one `findings[]` entry, in the contract's own order. */
+export const FINDING_FIELDS = [
+    "severity",
+    "category",
+    "description",
+    "suggested_fix",
+    "recurrence",
+    "introduced_by_delta",
+];
+/** Field names of the `reproduction` object, in the contract's own order. */
+export const REPRODUCTION_FIELDS = [
+    "method",
+    "sample_size",
+    "result",
+    "matches_implementer_claim",
+];
+/** Field names of one `withdrawn[]` entry, in the contract's own order. */
+export const WITHDRAWN_FIELDS = ["description", "reason"];
+/**
+ * Enum spellings keyed by their bare field name. Every enum-bearing field
+ * in the contract has a name unique across the whole block, so a flat map
+ * (rather than one keyed by full path) is enough and matches how the
+ * contract text itself reads (`key: a | b | c`).
+ */
+export const ENUM_VALUES = {
+    status: ["reviewed"],
+    role: ["reviewer"],
+    severity: ["low", "medium", "high", "critical"],
+    category: [
+        "correctness",
+        "architecture",
+        "security",
+        "tests",
+        "maintainability",
+        "performance",
+        "docs",
+    ],
+    recurrence: ["new", "repeated"],
+    introduced_by_delta: ["yes", "no", "unknown"],
+    acceptance_recommendation: [
+        "accept",
+        "accept_with_notes",
+        "fix_required",
+        "reject",
+    ],
+    matches_implementer_claim: ["matched", "mismatched", "not_applicable"],
+    method_applied: ["normal", "rigorous", "adversarial"],
+};
+/**
+ * This validator reports structural validity only. It does not judge
+ * semantic adequacy, cannot waive findings, and passing it does not
+ * constitute orchestrator acceptance.
+ */
+export const STRUCTURAL_ONLY_NOTE = "Structural check only: this does not judge semantic adequacy, cannot waive findings, and does not constitute orchestrator acceptance.";
+function describeValue(value) {
+    if (value === undefined)
+        return "missing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `array(length=${value.length})`;
+    if (typeof value === "object")
+        return "mapping";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    return String(value);
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function checkEnumField(record, key, allowed, path, diagnostics) {
+    const value = record[key];
+    const expected = allowed.join(" | ");
+    if (value === undefined) {
+        diagnostics.push({ path, expected, got: "missing" });
+        return;
+    }
+    if (typeof value !== "string" || !allowed.includes(value)) {
+        diagnostics.push({ path, expected, got: describeValue(value) });
+    }
+}
+function checkStringField(record, key, path, diagnostics) {
+    const value = record[key];
+    if (value === undefined) {
+        diagnostics.push({ path, expected: "string", got: "missing" });
+        return;
+    }
+    if (typeof value !== "string") {
+        diagnostics.push({ path, expected: "string", got: describeValue(value) });
+    }
+}
+function checkNonEmptyStringField(record, key, path, diagnostics) {
+    const value = record[key];
+    if (value === undefined) {
+        diagnostics.push({ path, expected: "non-empty string", got: "missing" });
+        return;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+        diagnostics.push({
+            path,
+            expected: "non-empty string",
+            got: describeValue(value),
+        });
+    }
+}
+/** Accepts a string or a number (a reviewer may write `sample_size: 5`). */
+function checkScalarField(record, key, path, diagnostics) {
+    const value = record[key];
+    if (value === undefined) {
+        diagnostics.push({ path, expected: "string or number", got: "missing" });
+        return;
+    }
+    if (typeof value !== "string" && typeof value !== "number") {
+        diagnostics.push({
+            path,
+            expected: "string or number",
+            got: describeValue(value),
+        });
+    }
+}
+function checkArrayField(doc, key, diagnostics) {
+    const value = doc[key];
+    if (value === undefined) {
+        diagnostics.push({ path: key, expected: "array", got: "missing" });
+        return;
+    }
+    if (!Array.isArray(value)) {
+        diagnostics.push({
+            path: key,
+            expected: "array",
+            got: describeValue(value),
+        });
+    }
+}
+/**
+ * Dispatch table keyed by every name in {@link FINDING_FIELDS}. The
+ * `Record<(typeof FINDING_FIELDS)[number], FieldChecker>` type means a
+ * name added to `FINDING_FIELDS` without a matching entry here is a
+ * TypeScript compile error, not a silently-unchecked field (fix-round,
+ * review finding M2).
+ */
+const FINDING_CHECKS = {
+    severity: (entry, path, diagnostics) => checkEnumField(entry, "severity", ENUM_VALUES.severity, `${path}.severity`, diagnostics),
+    category: (entry, path, diagnostics) => checkEnumField(entry, "category", ENUM_VALUES.category, `${path}.category`, diagnostics),
+    description: (entry, path, diagnostics) => checkStringField(entry, "description", `${path}.description`, diagnostics),
+    suggested_fix: (entry, path, diagnostics) => checkStringField(entry, "suggested_fix", `${path}.suggested_fix`, diagnostics),
+    recurrence: (entry, path, diagnostics) => checkEnumField(entry, "recurrence", ENUM_VALUES.recurrence, `${path}.recurrence`, diagnostics),
+    introduced_by_delta: (entry, path, diagnostics) => checkEnumField(entry, "introduced_by_delta", ENUM_VALUES.introduced_by_delta, `${path}.introduced_by_delta`, diagnostics),
+};
+/** Dispatch table keyed by every name in {@link REPRODUCTION_FIELDS}. */
+const REPRODUCTION_CHECKS = {
+    method: (value, path, diagnostics) => checkScalarField(value, "method", `${path}.method`, diagnostics),
+    sample_size: (value, path, diagnostics) => checkScalarField(value, "sample_size", `${path}.sample_size`, diagnostics),
+    result: (value, path, diagnostics) => checkScalarField(value, "result", `${path}.result`, diagnostics),
+    matches_implementer_claim: (value, path, diagnostics) => checkEnumField(value, "matches_implementer_claim", ENUM_VALUES.matches_implementer_claim, `${path}.matches_implementer_claim`, diagnostics),
+};
+/** Dispatch table keyed by every name in {@link WITHDRAWN_FIELDS}. */
+const WITHDRAWN_CHECKS = {
+    description: (entry, path, diagnostics) => checkStringField(entry, "description", `${path}.description`, diagnostics),
+    reason: (entry, path, diagnostics) => checkStringField(entry, "reason", `${path}.reason`, diagnostics),
+};
+function checkFindings(doc, diagnostics) {
+    const value = doc.findings;
+    if (value === undefined) {
+        diagnostics.push({ path: "findings", expected: "array", got: "missing" });
+        return;
+    }
+    if (!Array.isArray(value)) {
+        diagnostics.push({
+            path: "findings",
+            expected: "array",
+            got: describeValue(value),
+        });
+        return;
+    }
+    value.forEach((entry, index) => {
+        const path = `findings[${index}]`;
+        if (!isPlainRecord(entry)) {
+            diagnostics.push({
+                path,
+                expected: "mapping",
+                got: describeValue(entry),
+            });
+            return;
+        }
+        for (const field of FINDING_FIELDS) {
+            FINDING_CHECKS[field](entry, path, diagnostics);
+        }
+    });
+}
+function checkReproduction(doc, diagnostics) {
+    const value = doc.reproduction;
+    if (value === undefined) {
+        diagnostics.push({
+            path: "reproduction",
+            expected: "mapping",
+            got: "missing",
+        });
+        return;
+    }
+    if (!isPlainRecord(value)) {
+        diagnostics.push({
+            path: "reproduction",
+            expected: "mapping",
+            got: describeValue(value),
+        });
+        return;
+    }
+    for (const field of REPRODUCTION_FIELDS) {
+        REPRODUCTION_CHECKS[field](value, "reproduction", diagnostics);
+    }
+}
+function checkWithdrawn(doc, diagnostics) {
+    const value = doc.withdrawn;
+    if (value === undefined) {
+        diagnostics.push({
+            path: "withdrawn",
+            expected: "array (may be empty)",
+            got: "missing",
+        });
+        return;
+    }
+    if (!Array.isArray(value)) {
+        diagnostics.push({
+            path: "withdrawn",
+            expected: "array (may be empty)",
+            got: describeValue(value),
+        });
+        return;
+    }
+    value.forEach((entry, index) => {
+        const path = `withdrawn[${index}]`;
+        if (!isPlainRecord(entry)) {
+            diagnostics.push({
+                path,
+                expected: "mapping",
+                got: describeValue(entry),
+            });
+            return;
+        }
+        for (const field of WITHDRAWN_FIELDS) {
+            WITHDRAWN_CHECKS[field](entry, path, diagnostics);
+        }
+    });
+}
+/**
+ * Dispatch table keyed by every name in {@link TOP_LEVEL_FIELDS}. As with
+ * {@link FINDING_CHECKS}, the `Record<(typeof TOP_LEVEL_FIELDS)[number],
+ * DocChecker>` type turns a `TOP_LEVEL_FIELDS` entry without a matching
+ * checker into a TypeScript compile error (fix-round, review finding M2):
+ * a field added to both the contract fences and this array can no longer
+ * go unchecked while every test stays green, since it fails to typecheck
+ * before any test runs.
+ */
+const TOP_LEVEL_CHECKS = {
+    status: (doc, diagnostics) => checkEnumField(doc, "status", ENUM_VALUES.status, "status", diagnostics),
+    role: (doc, diagnostics) => checkEnumField(doc, "role", ENUM_VALUES.role, "role", diagnostics),
+    task_id: (doc, diagnostics) => checkNonEmptyStringField(doc, "task_id", "task_id", diagnostics),
+    summary: (doc, diagnostics) => checkArrayField(doc, "summary", diagnostics),
+    findings: checkFindings,
+    acceptance_recommendation: (doc, diagnostics) => checkEnumField(doc, "acceptance_recommendation", ENUM_VALUES.acceptance_recommendation, "acceptance_recommendation", diagnostics),
+    missing_tests: (doc, diagnostics) => checkArrayField(doc, "missing_tests", diagnostics),
+    residual_risks: (doc, diagnostics) => checkArrayField(doc, "residual_risks", diagnostics),
+    reproduction: checkReproduction,
+    method_applied: (doc, diagnostics) => checkEnumField(doc, "method_applied", ENUM_VALUES.method_applied, "method_applied", diagnostics),
+    withdrawn: checkWithdrawn,
+};
+/**
+ * The declared kind of every field of every contract constant, keyed by
+ * bare field name the way {@link ENUM_VALUES} is: a name is unique across
+ * the whole contract block except for `description`, which `findings[]`
+ * and `withdrawn[]` share with the same kind. The `satisfies
+ * Record<SchemaFieldName, FieldKind>` clause means a name added to any of
+ * the four constants without a kind here is a TypeScript compile error,
+ * the same way it is already an error to add one without a checker in the
+ * dispatch tables above. Were a future contract to reuse one name at two
+ * levels with two different kinds, this flat map could hold only one of
+ * them: the generator asserts each field's real diagnostics against its
+ * declared kind, so that shows up as a failing generated case rather than
+ * as an unchecked field.
+ */
+export const FIELD_KINDS = {
+    status: "enum",
+    role: "enum",
+    task_id: "non-empty-string",
+    summary: "array",
+    findings: "mapping-list",
+    acceptance_recommendation: "enum",
+    missing_tests: "array",
+    residual_risks: "array",
+    reproduction: "mapping",
+    method_applied: "enum",
+    withdrawn: "mapping-list",
+    severity: "enum",
+    category: "enum",
+    description: "string",
+    suggested_fix: "string",
+    recurrence: "enum",
+    introduced_by_delta: "enum",
+    method: "scalar",
+    sample_size: "scalar",
+    result: "scalar",
+    matches_implementer_claim: "enum",
+    reason: "string",
+};
+/**
+ * The `expected` text a diagnostic carries, per kind. `enum` is absent on
+ * purpose: its text is the enum's own spellings, read from
+ * {@link ENUM_VALUES}.
+ */
+const KIND_EXPECTED = {
+    string: "string",
+    "non-empty-string": "non-empty string",
+    scalar: "string or number",
+    array: "array",
+    "mapping-list": "array",
+    mapping: "mapping",
+};
+/**
+ * Fields whose diagnostic wording differs from their kind's default.
+ * `withdrawn`'s own text spells out that an empty list is fine, since a
+ * reviewer with nothing withdrawn must still emit the key.
+ */
+const EXPECTED_OVERRIDES = {
+    withdrawn: "array (may be empty)",
+};
+/**
+ * The `expected` text this validator's diagnostics about `field` carry.
+ * The checkers above hold that text literally, at their own push sites;
+ * this is the schema's declaration of the same text, which the generated
+ * test cases assert the checkers actually produce, so a checker whose
+ * behaviour stops matching its declared kind fails a case instead of
+ * drifting quietly.
+ */
+export function expectedTextFor(field) {
+    const override = EXPECTED_OVERRIDES[field];
+    if (override !== undefined)
+        return override;
+    const kind = FIELD_KINDS[field];
+    return kind === "enum" ? ENUM_VALUES[field].join(" | ") : KIND_EXPECTED[kind];
+}
+/** The `expected` text a diagnostic about one element of a `mapping-list` carries. */
+export const MAPPING_LIST_ELEMENT_EXPECTED = KIND_EXPECTED.mapping;
+/**
+ * A reviewer return is commonly wrapped in a single fenced code block.
+ * Strips one leading/trailing fence when present, whatever language tag
+ * it carries (```yaml, ```yml, a bare ``` , or any other tag -- a
+ * language-less fence previously fell through to the "literal YAML"
+ * branch below and produced a confusing YAML parse error instead of a
+ * clean structural diagnostic; fix-round, review finding L2); anything
+ * unfenced is treated as literal YAML. The fence is located anywhere in
+ * the input, not only at its very start: a return prefixed with prose
+ * ("Here is my report:\n```yaml ...") previously fell through to the
+ * "literal YAML" branch, since the fence pattern was anchored to the
+ * start of the string, and produced a raw parse error instead of a
+ * structural diagnostic (fix-round, review finding L1). Prose found
+ * before the opening fence or after the closing fence is tolerated, but
+ * each is named as its own warning rather than silently dropped.
+ *
+ * The closing fence must start at column 0: the pattern anchors it with
+ * `^` under the `m` flag, so a triple-backtick sequence inside a value
+ * (a reviewer quoting a fenced snippet in a `description` block scalar,
+ * which YAML necessarily indents) can no longer close the block early
+ * and hand the parser a truncated document, which surfaced as
+ * diagnostics about fields the return actually carried (fix-round,
+ * review finding L3).
+ */
+export function extractYamlSource(raw) {
+    const warnings = [];
+    // No BOM handling: the yaml parser accepts a leading U+FEFF and the
+    // fenced path trims it away with the surrounding prose.
+    const withoutBom = raw;
+    const fenceMatch = withoutBom.match(/```[A-Za-z]*\r?\n([\s\S]*?)\r?\n?^```/m);
+    if (fenceMatch) {
+        const start = fenceMatch.index ?? 0;
+        const before = withoutBom.slice(0, start);
+        if (before.trim().length > 0) {
+            warnings.push("prose found before the opening ```yaml fence; only the fenced block was validated");
+        }
+        const inner = fenceMatch[1];
+        const after = withoutBom.slice(start + fenceMatch[0].length);
+        if (after.trim().length > 0) {
+            warnings.push("prose found after the closing ```yaml fence; only the fenced block was validated");
+        }
+        return { yamlText: inner, warnings };
+    }
+    return { yamlText: withoutBom, warnings };
+}
+/**
+ * Validates a reviewer return against the reviewer output contract's
+ * structure. Reports structural validity ONLY: it never judges semantic
+ * adequacy, never waives a finding, and passing it is never orchestrator
+ * acceptance.
+ */
+export function validateReviewReport(raw) {
+    const diagnostics = [];
+    const { yamlText, warnings } = extractYamlSource(raw);
+    let parsed;
+    try {
+        parsed = parseYaml(yamlText);
+    }
+    catch (error) {
+        diagnostics.push({
+            path: "<root>",
+            expected: "valid YAML",
+            got: error instanceof Error ? error.message : String(error),
+        });
+        return { valid: false, diagnostics, warnings };
+    }
+    if (!isPlainRecord(parsed)) {
+        diagnostics.push({
+            path: "<root>",
+            expected: "a YAML mapping (object)",
+            got: describeValue(parsed),
+        });
+        return { valid: false, diagnostics, warnings };
+    }
+    for (const field of TOP_LEVEL_FIELDS) {
+        TOP_LEVEL_CHECKS[field](parsed, diagnostics);
+    }
+    return { valid: diagnostics.length === 0, diagnostics, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",
@@ -47,7 +47,8 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "inquirer": "^9.2.0"
+    "inquirer": "^9.2.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@iarna/toml": "^2.2.5",