orchestrator-workflow 0.35.0 → 0.37.0

package/dist/review-report.js

@@ -0,0 +1,554 @@
+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),
+        });
+    }
+}
+/**
+ * Checks a top-level `array`-kind field (`summary`, `missing_tests`,
+ * `residual_risks`): the contract writes each of these as a plain list of
+ * strings (`- ""`), so every element that is not a string is its own
+ * diagnostic at `<key>[<index>]`, `expected: "string"`, alongside the
+ * container-level checks. All offending elements are reported, not only
+ * the first, the same way {@link checkFindings} reports every non-mapping
+ * `findings[]` entry rather than stopping at one.
+ *
+ * Emptiness is deliberately not judged here: an element that is an
+ * explicitly quoted empty or blank string (`- ""`, `- "   "`) is still a
+ * string and passes, the same tolerance {@link checkStringField}'s plain
+ * `"string"` kind gives a top-level field (unlike
+ * {@link checkNonEmptyStringField}'s `"non-empty-string"` kind, which
+ * `task_id` uses). A bare `- ` or `- ~` bullet is not a string at all --
+ * YAML parses either as `null`, which this checker rejects the same as
+ * any other non-string element; only a quoted placeholder passes. These
+ * three fields are declared `"array"` in {@link FIELD_KINDS}, not
+ * `"non-empty-string"`, so a quoted element gets the same tolerance its
+ * own kind implies; a reviewer emitting a quoted placeholder blank bullet
+ * is a content question the orchestrator judges, not a structural one
+ * this validator judges.
+ */
+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),
+        });
+        return;
+    }
+    value.forEach((element, index) => {
+        if (typeof element !== "string") {
+            diagnostics.push({
+                path: `${key}[${index}]`,
+                expected: "string",
+                got: describeValue(element),
+            });
+        }
+    });
+}
+/**
+ * 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;
+/** The `expected` text a diagnostic about one non-string element of a plain `array`-kind field (`summary`, `missing_tests`, `residual_risks`) carries. */
+export const ARRAY_ELEMENT_EXPECTED = KIND_EXPECTED.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 opening fence's whole backtick run is captured, and the closing
+ * fence must be a run at least as long, starting at column 0, with
+ * nothing but whitespace after it (CommonMark's own rule): the pattern
+ * backreferences the captured run and 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);
+ * and a return a reviewer wrapped in four backticks precisely because
+ * it contains a fence of its own is closed by its own four-backtick run
+ * rather than by that inner one. Matching a fixed three backticks
+ * instead of the run left a longer opener's remaining backticks in the
+ * info string, which read as the tag `` `yaml `` and matched no
+ * yaml/yml fence at all. The OPENING fence keeps its own position
+ * discipline unchanged: it is located anywhere in the input rather than
+ * anchored to a line start.
+ *
+ * Lookarounds on both sides of the run keep it whole, so the opening
+ * run is never re-entered at a shorter length. Without them, an input
+ * whose long backtick run has no valid closer is retried at every
+ * shorter run length from every offset inside the run, each retry
+ * rescanning the lazy body: work quadratic in the run's length, which a
+ * single pasted return of a few hundred backticks already turns into
+ * seconds (CHANGELOG [Unreleased] names the measurement). Keeping the
+ * run whole also makes the "closing run at least as long as the opening
+ * one" rule above literal: an opener longer than any closing run in the
+ * input is no fence at all, where splitting the run instead matched it
+ * and pushed the leftover backticks into the info string. One cost
+ * stays: every backtick run is still tried as an opener candidate, and a
+ * candidate with no qualifying closer scans to the end of the input, so
+ * an input of many runs with no valid closer costs work quadratic in the
+ * number of runs (well under a second at several thousand runs; a
+ * well-formed return is unaffected). Anchoring the opener to a line
+ * start would remove it, at the price of the position-free opener the
+ * paragraph above keeps.
+ *
+ * When the input carries more than one fenced block (a reviewer pasting
+ * a worked example ahead of the real return, say), the FIRST fence whose
+ * info string's first whitespace-delimited word is `yaml` or `yml`
+ * (case-insensitive) is preferred over every earlier fence, tagged or
+ * not; only when none of the fences carries that word does today's
+ * original first-fence behaviour apply. The whole info string is
+ * captured, not only a leading run of letters, so a tag followed by
+ * attributes (` ```yaml title=x `) is still recognised as `yaml` --
+ * previously the capture stopped at the first non-letter and required a
+ * newline right after it, so an attribute-bearing info string matched no
+ * fence at all, tagged or not; this also widens the untagged first-fence
+ * fallback, so an attribute-bearing fence with no yaml/yml word is at
+ * least recognised as a fence. This preference rule is not free of
+ * surprises of its own: a reviewer whose own return is left unfenced and
+ * who then quotes a ```yaml example afterward has that later example
+ * validated instead of their real return, which the emitted warning
+ * names. Preferring a later, differently-positioned fence over
+ * `fences[0]` is itself named as a warning, distinct from the existing
+ * before/after prose warnings; the before-warning is suppressed when the
+ * text preceding the chosen fence consists only of the skipped fence(s)
+ * and whitespace, since calling a legitimate (if unpreferred) fenced
+ * block "prose" alongside the skip warning that already names it is
+ * redundant; real prose ahead of a skipped fence still warns as before.
+ */
+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 fences = [
+        ...withoutBom.matchAll(/(?<!`)(`{3,})(?!`)([^\r\n]*)\r?\n([\s\S]*?)\r?\n?^\1`*[ \t]*$/gm),
+    ];
+    if (fences.length > 0) {
+        const fenceTag = (info) => info.trim().split(/\s+/, 1)[0] ?? "";
+        const yamlTaggedIndex = fences.findIndex((match) => /^(?:yaml|yml)$/i.test(fenceTag(match[2])));
+        const chosenIndex = yamlTaggedIndex >= 0 ? yamlTaggedIndex : 0;
+        const chosen = fences[chosenIndex];
+        if (chosenIndex > 0) {
+            const skippedCount = chosenIndex;
+            const noun = skippedCount === 1 ? "block" : "blocks";
+            const verb = skippedCount === 1 ? "was" : "were";
+            warnings.push(`${skippedCount} earlier fenced ${noun} without a yaml/yml tag ${verb} skipped in favor of the later \`${fenceTag(chosen[2])}\` fenced block; only that later block was validated`);
+        }
+        const start = chosen.index ?? 0;
+        const before = withoutBom.slice(0, start);
+        const beforeIsOnlySkippedFences = chosenIndex > 0 &&
+            fences
+                .slice(0, chosenIndex)
+                .reduce((text, skipped) => text.replace(skipped[0], ""), before)
+                .trim().length === 0;
+        if (before.trim().length > 0 && !beforeIsOnlySkippedFences) {
+            warnings.push("prose found before the opening ```yaml fence; only the fenced block was validated");
+        }
+        const inner = chosen[3];
+        const after = withoutBom.slice(start + chosen[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.37.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",