orchestrator-workflow 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -7,6 +7,215 @@ 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
+  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,59 @@ 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. 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
+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

@@ -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
@@ -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

@@ -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
 
@@ -165,6 +165,43 @@ 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; 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
 one that already appeared in an earlier round. On a task's first review

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/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;