orchestrator-workflow 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -7,6 +7,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-09-18
+
+- The two verdict fields of a mutation probe now carry a legend, a source
+  and a check. `assets/agents/implementer.md`, the normative site for the
+  output-field semantics, says: "`result: killed` means the probe's test
+  command reacted to the mutant under the runner's own pass predicate and
+  `survived` means it did not; `expectation: met` means that outcome is what
+  the probe was expected to show and `violated` means it is not; both are
+  `not_applicable` when no `result` was measured." and: "When the probe
+  runner states a machine-readable verdict, copy whichever of `result` and
+  `expectation` it states from it verbatim, never from your own reading of
+  the test output; when it states only `result`, set `expectation` by
+  comparing that verdict with the probe's declared expectation. Quote the
+  runner's verdict for each probe in `tests.executed`, and say there when
+  `expectation` was set this way, so both fields can be checked against it."
+  `references/contracts.md` carries both sentences verbatim for the
+  orchestrator. Step 6 of `references/evidence-and-probes.md` adds the
+  orchestrator's side: "Before transferring a probe row, compare its
+  `result` and `expectation` with the runner verdict quoted in
+  `tests.executed`; on a mismatch, or when a verdict the runner states is
+  not quoted, resupply it (ask the same implementer for the verdict, respawn
+  one when it is gone, or rerun the probe yourself in isolation), record the
+  resupply in `03-decisions.md`, and treat it as a transfer blocker rather
+  than a misfire, since the return itself parses; never infer either field.
+  A quoted probe verdict is not a named result of the verification set, so
+  the set's missing-or-extra rule does not apply to it." The contract shape,
+  the enums and the eleven `mutation_probes` sub-fields are unchanged, no
+  tool is named, and every sentence was appended to an existing line so no
+  cited line moved (the prompt is cited by line throughout the knowledge
+  bundle); the prompt change reaches an existing install with the next kit
+  re-install, which also re-renders the tier variants. Evidence (issue #300,
+  one run, not a benchmark): an implementer returned all six probes as
+  `survived` with `expectation: violated` while its own evidence showed the
+  suite failing on every mutant, and the mislabel was caught only because
+  the orchestrator compared the fields with that evidence by hand. Pinned in
+  `test/probe-plans-recovery.test.ts`.
+- Three ceremony rules in the skill references, none of which changes the
+  review gate, the waiver rules or the AGENTS.md section (byte-identical, so
+  no AGENTS.md re-install is needed; the rules reach an existing install
+  with the next kit re-install). Step 6 of
+  `references/evidence-and-probes.md` now says: "Record a baseline revision
+  only when scope or the normative text of a criterion changes, including a
+  change to what its verification checks; a wording precision that leaves
+  the check itself unchanged is a `03-decisions.md` entry, not a revision";
+  the orchestrator records that entry, states in it why no evidence is
+  invalidated, and communicates the corrected wording in the next
+  delegation. Step 7 now says: "For a review round whose entire delta is a
+  docs-only delta in the sense of step 8's docs-only closure, default to the
+  `-medium` reviewer tier with `review_method: normal` where tier variants
+  are installed". That refines the general tier default for this one class
+  only, a round that touches an instruction, policy, template or prompt file
+  keeps the general default, and the minimum review methods are untouched;
+  the AGENTS.md section does not yet point to this refinement.
+  `references/review-and-recovery.md` gains a "Pinned-prose changes" section
+  for a change whose acceptance rests on tests that pin documentation
+  wording: "A prose mutant survives exactly when its bytes sit in no
+  assertion", so review rounds that hunt for the next unpinned sentence do
+  not converge. The section asks for one normative site per rule, a claim
+  list in the acceptance criterion as the pin obligation (every normative
+  sentence the change adds or alters at that site is a claim, an omission is
+  named with its reason), a reviewer briefing that bounds the prose mutant
+  space to that list, copies bound to the normative site by one shared test
+  constant, and: "Cap test-adequacy review rounds on the change at two." It
+  defines the capped round, exempts semantic findings, and changes neither
+  the Round-2 halt rule, the escalation budget, the Fix-regression decision
+  point nor the review gate. Step 7 points to the section without restating
+  it. Evidence (issue #300 and the change that added the Fix-regression
+  decision point; one repository each, not a benchmark): the issue reports
+  baseline revisions r1 to r3 for two wording precisions of a verification
+  method, and a run in which the top reviewer tier was about half the day's
+  cost across nine reviewer rounds and an advisor, where the documentation
+  rounds did not need that tier; the decision point itself, about 27 lines
+  of rule text, took four review rounds with unpinned prose reported in
+  every one, until the trigger was held in one test constant and the mutant
+  space was bounded. Pinned in `test/probe-plans-recovery.test.ts`.
+- `references/review-and-recovery.md` gains a "Fix-regression decision
+  point" between the Review-round escalation budget and the Final
+  acceptance rule: when the review of a fix round reports at least one
+  `high` or `critical` finding that the previous round's review did not
+  report, with `introduced_by_delta: yes`, the orchestrator names in one
+  sentence why the fix could introduce it and records one of four outcomes
+  in `03-decisions.md` (continue with the stated reason, redesign, split,
+  hold) before another fix round starts. It is a decision point, not a
+  halt, and changes neither the Round-2 halt rule nor the budget. The
+  rule is defined only in that section; step 8 of
+  `references/evidence-and-probes.md` points to it without restating the
+  trigger. The AGENTS.md section is unchanged, so no AGENTS.md re-install
+  is needed; the rule reaches an existing install with the next kit
+  re-install, like any other skill-reference change. Evidence (issue #300,
+  one repository, one model mix, not a benchmark): in a five-round run the
+  third review already showed that the fix had introduced new high
+  findings, but the defect class only recurred in the fourth review, so
+  the halt rule fired one round, about an hour, after the structural
+  problem was visible. Pinned in `test/probe-plans-recovery.test.ts`.
+- `validate-review-report` now checks that every element of a string-array
+  field (`summary`, `missing_tests`, `residual_risks`) is a string, one
+  diagnostic per offending element at `<field>[<index>]`; and
+  `extractYamlSource` now prefers a fenced block tagged `yaml`/`yml` when
+  several fences are present, falling back to the first fence only when
+  none carries that tag, with a warning naming the earlier fence it
+  skipped. The fence tag is now matched against the whole info string's
+  first whitespace-delimited word rather than a leading run of letters,
+  so a tag followed by attributes (a fence opened `yaml title=x`) is
+  recognized as `yaml` instead of matching no fence at all. The "prose
+  found before" warning no longer also fires when the text preceding the
+  preferred fence is exactly the skipped fence(s) plus whitespace, so a
+  skipped fence is no longer double-reported as both skipped and prose.
+  The opening fence's backtick run is now consumed whole and the closing
+  fence must repeat at least as many backticks at column 0 with nothing
+  but whitespace after it, so a return opened with four backticks is
+  recognized as `yaml` (the run's leftover backticks previously landed in
+  the info string, making the tag itself start with a backtick) and ends
+  at its own four-backtick run rather than at a three-backtick line
+  inside it. Widening the info-string capture also widens what counts as
+  a fence at all: any attribute-bearing fence, and any fence opened with
+  more than three backticks, is now a fence, so input whose only fence
+  was opened `js title=x` is treated as fenced rather than as literal
+  YAML. Only whitespace-separated attributes count toward the tag:
+  `yaml title=x` counts, `yaml,title=x` does not, its first word being
+  the whole string. That opening run is now matched whole and never
+  re-entered at a shorter length, which bounds the scan: a run with no
+  valid closer was previously retried at every shorter run length from
+  every offset inside the run, each retry rescanning the block body, so
+  a 2000-backtick run in a 22 KB return took roughly 50 seconds through
+  `extractYamlSource` where it now takes under a millisecond. Keeping
+  the run whole also makes the closing-length rule literal: a return
+  whose opening run is longer than every closing run in it is no fence
+  at all and reaches the parser whole, where splitting the run
+  previously matched it and read its leftover backticks as the start of
+  the tag.
+
+- `check-release-changelogs`'s `VERSION_HEADING_RE` (rule 1, version-heading)
+  now accepts the same prerelease identifier class as `parseSemver`
+  (`[0-9A-Za-z.-]`, including the hyphen), sourced from one shared
+  `PRERELEASE_IDENTIFIER_CHARS` constant so the two cannot drift apart
+  again: a package.json version with a hyphenated prerelease tag such as
+  `1.0.0-alpha-1` parsed fine through `parseSemver` but previously never
+  matched the heading regex, which only accepted `[\w.]`. The previous
+  0.35.0 hardening bullet named the new rules without naming three
+  details of their own contract: the `--expect <csv>` option overrides
+  rule 5's (checked-package-scope) expectation list, and an empty csv
+  (`--expect ""`) opts out of rule 5 entirely rather than passing it
+  vacuously; rule 5 itself only runs when that expectation list is
+  non-empty, so a fixture whose packages do not share this repo's names
+  can still run the other four rules without a spurious finding; and
+  rule 2's (fresh-unreleased) direction check compares versions by
+  semver precedence, not string inequality, with build metadata stripped
+  before the comparison since two versions differing only in build
+  metadata carry equal precedence per the semver spec. The shared class
+  is narrower than `\w`: an underscore prerelease heading such as
+  `1.0.0-alpha_1` is no longer accepted either, since semver's own
+  prerelease grammar forbids underscores and `parseSemver` already
+  rejected such a version before this change.
+
 ## [0.36.0] - 2026-09-16
 
 - A `validate-review-report <file>` CLI subcommand (`-` reads stdin) checks a

package/README.md

@@ -705,17 +705,35 @@ 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).
+diagnostic per missing or invalid field. Every element of a string-array
+field (`summary`, `missing_tests`, `residual_risks`) must itself be a
+string; a non-string element (a number, a mapping, a boolean, or `null`
+-- written as a bare or `~` bullet) is its own diagnostic at
+`<field>[<index>]`. A fenced return ends at the first closing fence that
+starts at column 0, repeats at least as many backticks as the opening
+fence, and carries nothing but whitespace after that run, so neither a
+reviewer quoting a fenced snippet inside a value (a `description` block
+scalar, which YAML indents) nor one wrapping a return in four backticks
+around a snippet fenced at column 0 truncates the return. A return
+with no closing fence satisfying all three is not fenced at all, so its
+whole text reaches the parser; that includes one whose opener is longer
+than every closing run present. When the return carries more than one
+fenced block, the first one whose fence tag's first word is `yaml` or
+`yml` is validated, case-insensitively and counting whitespace-separated
+attributes (`yaml title=x` counts; `yaml,title=x` does not, its first
+word being the whole string), falling back to the first fence only when
+none carries that word; a warning names any earlier fence skipped this
+way. This preference can validate a later worked example instead of an
+earlier, real but unfenced return: a reviewer who leaves their own return
+unfenced and then quotes a `yaml`-tagged example afterward has that
+example validated instead, which the emitted warning also names.
+`--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

package/assets/agents/implementer.md

@@ -103,7 +103,7 @@ Rules:
   from its result fields (`verified_applied_via`, `result`, `expectation`,
   `reason`, `restored_verified`), take the definition fields from that
   mutant record so the copied report still carries all eleven
-  `mutation_probes` sub-fields.
+  `mutation_probes` sub-fields. `result: killed` means the probe's test command reacted to the mutant under the runner's own pass predicate and `survived` means it did not; `expectation: met` means that outcome is what the probe was expected to show and `violated` means it is not; both are `not_applicable` when no `result` was measured. When the probe runner states a machine-readable verdict, copy whichever of `result` and `expectation` it states from it verbatim, never from your own reading of the test output; when it states only `result`, set `expectation` by comparing that verdict with the probe's declared expectation. Quote the runner's verdict for each probe in `tests.executed`, and say there when `expectation` was set this way, so both fields can be checked against it.
 - Run every long test, build, or mutation-probe command in the foreground
   and wait for it to finish before returning. When one foreground call
   cannot hold it to completion, poll the backgrounded run to completion

package/assets/skill/references/contracts.md

@@ -126,7 +126,7 @@ commits:
 Follow [evidence-and-probes.md workflow step 6](evidence-and-probes.md#workflow)
 for implementation evidence, verification, mutation probes, and replay. For
 output-field semantics and commit reporting, follow the installed
-implementer role prompt. Return the selected contract's YAML envelope.
+implementer role prompt. Return the selected contract's YAML envelope. `result: killed` means the probe's test command reacted to the mutant under the runner's own pass predicate and `survived` means it did not; `expectation: met` means that outcome is what the probe was expected to show and `violated` means it is not; both are `not_applicable` when no `result` was measured. When the probe runner states a machine-readable verdict, copy whichever of `result` and `expectation` it states from it verbatim, never from your own reading of the test output; when it states only `result`, set `expectation` by comparing that verdict with the probe's declared expectation. Quote the runner's verdict for each probe in `tests.executed`, and say there when `expectation` was set this way, so both fields can be checked against it.
 
 ## Reviewer output contract
 
@@ -166,22 +166,41 @@ 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.
+`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; every element of
+a string-array field (`summary`, `missing_tests`, `residual_risks`) must
+itself be a string, with a diagnostic at `<field>[<index>]` for each one
+that is not (a number, a mapping, a boolean, and `null` -- a bare or `~`
+bullet -- are all rejected the same way). A fenced return ends at the
+first closing fence that starts at column 0, repeats at least as many
+backticks as the opening one, and carries nothing but whitespace after
+that run, so a return wrapped in four backticks may quote a snippet
+fenced in three without truncating itself; a return with no closing
+fence satisfying all three is not fenced at all and reaches the parser
+whole, including one whose opener is longer than every closing run
+present. When more than one fenced block
+is present, the first one whose fence tag's first word is `yaml` or `yml`
+is validated, case-insensitively and counting whitespace-separated
+attributes (`yaml title=x` counts; `yaml,title=x` does not, its first
+word being the whole string), falling back to the first fence only when
+none carries that word, with a warning naming any earlier fence skipped
+this way. The same preference can validate a later worked example instead
+of an earlier, real but unfenced return, which the emitted warning also
+names. 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

package/assets/skill/references/evidence-and-probes.md

@@ -112,7 +112,7 @@ directory and the subagents.
    `03-decisions.md` and consolidate evidence in
    `04-implementation-summary.md`, recording each probe the implementer
    reports as a row in `04-implementation-summary.md`'s Mutation Probes
-   subsection, with the round it was named in. Each row's Before/After
+   subsection, with the round it was named in. Before transferring a probe row, compare its `result` and `expectation` with the runner verdict quoted in `tests.executed`; on a mismatch, or when a verdict the runner states is not quoted, resupply it (ask the same implementer for the verdict, respawn one when it is gone, or rerun the probe yourself in isolation), record the resupply in `03-decisions.md`, and treat it as a transfer blocker rather than a misfire, since the return itself parses; never infer either field. A quoted probe verdict is not a named result of the verification set, so the set's missing-or-extra rule does not apply to it. Each row's Before/After
    cells hold a single-line excerpt; when the mutant's actual before/after
    text is multi-line or contains an unescaped `|`, or the mutant is a
    patch/diff rather than a text swap, the full text or diff goes in the
@@ -137,7 +137,7 @@ directory and the subagents.
    acceptance; the coverage index is not a results database or acceptance
    engine. Only the orchestrator can explicitly revise a baseline, recording
    old/new revisions, affected IDs, authority and reason, invalidated evidence,
-   and verified rationale for carrying unchanged evidence forward.
+   and verified rationale for carrying unchanged evidence forward. Record a baseline revision only when scope or the normative text of a criterion changes, including a change to what its verification checks; a wording precision that leaves the check itself unchanged is a `03-decisions.md` entry, not a revision: the orchestrator records it, states in that entry why no evidence is invalidated, and communicates the corrected wording in the next delegation.
 7. **Delegate review.** Send the diff to the reviewer subagent, naming in the
    briefing the base and head revision the diff was generated from. When tier
    variants are installed, pick the reviewer tier (the installed
@@ -152,7 +152,7 @@ directory and the subagents.
    cosmetics; `rigorous` otherwise. The method is orthogonal to the tier and
    never substitutes for it: do not pair `adversarial` with the `-medium`
    reviewer tier, a budget mismatch that names probes without the effort to run
-   them; tiers themselves are unchanged by this axis. When the reviewer's
+   them; tiers themselves are unchanged by this axis. For a review round whose entire delta is a docs-only delta in the sense of step 8's docs-only closure, default to the `-medium` reviewer tier with `review_method: normal` where tier variants are installed. This refines the general tier default above for that one class only: there `-medium` is the default and a higher tier is the non-default choice recorded with a one-line reason. A review round that touches an instruction, policy, template or prompt file keeps the general default, whatever the file type, and the minimums named above are unaffected. For a change whose acceptance rests on tests that pin documentation wording, write the briefing as the Pinned-prose changes section of [review and recovery](review-and-recovery.md) requires. When the reviewer's
    environment cannot use version control to see the diff (for example a
    policy-gated repository), supply the diff as a pre-generated file in the
    briefing instead of expecting the reviewer to derive it, and have the
@@ -226,7 +226,7 @@ directory and the subagents.
    halt signal across repeated review-fix cycles (see Round-2 halt rule
    below). By the second round-2 halt signal or the third `fix_required`
    review round on the same task, apply the Review-round escalation budget
-   (see below) instead of running another round unaided. At an advisor
+   (see below) instead of running another round unaided. When a fix round's review meets the trigger of the Fix-regression decision point (defined only in [review and recovery](review-and-recovery.md), not restated here), record the Fix-regression decision point before another fix round starts. At an advisor
    trigger (architectural uncertainty, conflicting
    requirements, a high-commitment fork among valid options, repeated
    implementation failures, a review deadlock, a high-risk decision), the

package/assets/skill/references/review-and-recovery.md

@@ -82,6 +82,72 @@ through the reviewer subagent in full; this budget forces a change in
 approach, not a shortcut past the review gate. Anchored by a measurement;
 see the entry for this rule in the orchestrator-workflow CHANGELOG.
 
+## Fix-regression decision point
+
+The signal: the review of a fix round (any implementation round after the
+task's first) reports at least one `high` or `critical` finding that the
+previous round's review did not report, with `introduced_by_delta: yes`, so
+the fix itself broke something. Read the qualifier off the findings of the
+two reviews, not off `recurrence`: a `recurrence: repeated` finding that
+the previous round's review did not report still triggers it. `unknown` and
+`no` do not trigger this decision point: `no` continues through the
+ordinary finding gate, and `unknown` keeps its existing treatment under the
+Round-2 halt rule and the escalation budget. The signal needs no
+recurrence: it fires even when the new finding's defect class has not
+appeared on this task before, which is what separates it from the Round-2
+halt rule above.
+
+Before another fix round starts, name in one sentence why the fix could
+introduce the defect (the structural cause, or the statement that there is
+none), and record one of four outcomes as a decision in `03-decisions.md`:
+continue with the stated reason, redesign, split, or hold (a merge-hold to
+the operator). Spawning the advisor for this decision is optional.
+
+This is a decision point, not a halt: continuing is a valid outcome, it is
+not a round-2 halt signal, and it does not count toward the Review-round
+escalation budget (the negative round itself still counts there as
+before). It never replaces a review round. When the same review also fires
+the Round-2 halt signal, the halt rule governs and this record is folded
+into its split-or-redesign decision. Anchored by an observed run; see the
+entry for this rule in the orchestrator-workflow CHANGELOG.
+
+## Pinned-prose changes
+
+This applies to a change whose acceptance rests on tests that pin
+documentation wording (a rule text asserted by string match). A prose
+mutant survives exactly when its bytes sit in no assertion, so a surviving
+mutant alone says nothing about quality, and review rounds that hunt for
+the next unpinned sentence do not converge. For such a change:
+
+- Name one normative site per rule when slicing; every other site that
+  states the rule is a copy.
+- List the load-bearing claims of the normative site in the acceptance
+  criterion, and pin each one as the whole sentence or clause that carries
+  it. That list is the pin obligation. Every normative sentence the change
+  adds or alters at that site is a claim; one left off the list is named
+  in the criterion with the reason it is not load-bearing.
+- Bound the reviewer's prose mutant space to that list in the briefing. A
+  survivor outside the list is a scope note in the reviewer's
+  `residual_risks`, not a finding, unless the reviewer shows that the
+  unlisted sentence is load-bearing.
+- Bind each copy to the normative site through one shared test constant,
+  and let a pointer point without restating the rule.
+- Cap test-adequacy review rounds on the change at two. A test-adequacy
+  review round is one whose only unresolved findings are `tests` findings
+  about pin gaps on the pinned prose; a round with any other unresolved
+  finding is an ordinary round outside the cap. Pin gaps that remain
+  become accepted notes or a follow-up.
+
+Semantic findings are exempt from the bound and from the cap: two sites
+stating different rules, a contradiction with another rule, and a false
+claim are defects at whatever severity they deserve. The cap changes
+neither the Round-2 halt rule, the Review-round escalation budget nor the
+Fix-regression decision point: a capped round still counts as a negative
+round where it is one. The review gate is unchanged: a high or critical
+finding of any category still blocks and is never capped away, and
+accepting one follows the waiver rules. Anchored by an observed run; see
+the entry for this rule in the orchestrator-workflow CHANGELOG.
+
 ## Final acceptance rule
 
 Subagents provide evidence. The orchestrator decides. The operator receives

package/dist/review-report.d.ts

@@ -59,7 +59,9 @@ export type SchemaFieldName = (typeof TOP_LEVEL_FIELDS)[number] | (typeof FINDIN
  * - `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.
+ * - `array`: present and an array; an empty array is accepted, and every
+ *   element must be a string (each non-string element is its own
+ *   diagnostic at `<field>[<index>]`; see {@link checkArrayField}).
  * - `mapping-list`: `array`, and every element a mapping.
  * - `mapping`: present and a mapping.
  *
@@ -118,6 +120,8 @@ export declare const FIELD_KINDS: {
 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;
+/** The `expected` text a diagnostic about one non-string element of a plain `array`-kind field (`summary`, `missing_tests`, `residual_risks`) carries. */
+export declare const ARRAY_ELEMENT_EXPECTED: string;
 interface ExtractedYaml {
     yamlText: string;
     warnings: string[];
@@ -138,13 +142,66 @@ interface ExtractedYaml {
  * 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).
+ * 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 declare function extractYamlSource(raw: string): ExtractedYaml;
 /**

package/dist/review-report.js

@@ -145,6 +145,29 @@ function checkScalarField(record, key, path, diagnostics) {
         });
     }
 }
+/**
+ * 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) {
@@ -157,7 +180,17 @@ function checkArrayField(doc, key, diagnostics) {
             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
@@ -368,6 +401,8 @@ export function expectedTextFor(field) {
 }
 /** 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
@@ -384,28 +419,98 @@ export const MAPPING_LIST_ELEMENT_EXPECTED = KIND_EXPECTED.mapping;
  * 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).
+ * 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 fenceMatch = withoutBom.match(/```[A-Za-z]*\r?\n([\s\S]*?)\r?\n?^```/m);
-    if (fenceMatch) {
-        const start = fenceMatch.index ?? 0;
+    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);
-        if (before.trim().length > 0) {
+        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 = fenceMatch[1];
-        const after = withoutBom.slice(start + fenceMatch[0].length);
+        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");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.36.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",