orchestrator-workflow 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -7,6 +7,117 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.39.0] - 2026-09-23
+
+- The docs-only review default now states its condition directly instead
+  of borrowing step 8's closure term: a review round whose entire delta
+  contains only explanatory documentation, comments, or citations, with no
+  source- or test-file edits and no semantic change to executable commands,
+  configuration, policy, instructions, or behavior, defaults to the
+  `-medium` reviewer tier with `review_method: normal`. The pinned-prose
+  cap counts a test-adequacy review round as one whose returned findings are
+  all `low` or `medium` `tests` findings about pin gaps; every normative
+  sentence a change adds or alters at its site is pinned, and one left
+  unpinned is named with the reason it is not load-bearing; a reviewer
+  respects a briefing that bounds the prose mutant space to a claim list
+  (#332).
+
+- Clarified the review-round tier/model escalation path for `single` and
+  rewrapped the installed policy fence with its cited documentation.
+
+- Mutation-probe verdict reporting now distinguishes runner-supplied,
+  result-only, and no-verdict cases without changing the output contract.
+  `result: killed` means the probe's test command reacted to the mutant
+  under the runner's pass predicate, or the test pass predicate declared
+  in the task assignment or probe plan when no runner supplies a verdict;
+  `survived` means it did not. `expectation: met` means the measured
+  result matches the expected result declared in the task assignment or
+  probe plan, and `violated` means it does not; both fields are
+  `not_applicable` when no result was measured. When a mutation-probe
+  runner is available, run the named probes through it and copy every
+  supplied `result` and `expectation` verbatim into `mutation_probes`,
+  never substituting your interpretation of its test output. Quote each
+  supplied verdict in `tests.executed`; when it supplies only `result`,
+  derive `expectation` from the expected result declared in the task
+  assignment or probe plan, and identify that declaration and derivation
+  there. When no machine-readable verdict is available, state that
+  explicitly in `tests.executed`, identify the declared test pass
+  predicate and expected result, and quote the observed baseline and
+  mutant outcomes. Derive `result` from those observations only when the
+  baseline passed, mutant application was verified, and the mutant test
+  completed under the same command and predicate; derive `expectation` by
+  comparing that result with the declared expected result, and label both
+  derivations as manual. Before transferring a probe row, compare each
+  copied field with the quoted verdict and each derived field with its
+  stated declaration and evidence. An explicit absence of a
+  machine-readable verdict requires the manual comparison, not resupply of
+  a nonexistent verdict. On a mismatch or missing required evidence,
+  obtain corrected evidence from the implementer or rerun the probe in
+  isolation, record the action in `03-decisions.md`, and keep the row
+  blocked from transfer until the comparison succeeds; if the evidence
+  cannot be obtained, record the unresolved proof rather than repeatedly
+  requesting an unavailable verdict. Never invent a verdict, override a
+  supplied field, or fill an unsupported derivation. Apply the same
+  evidence reporting and comparison to probes you run yourself before
+  recording their rows in `04-implementation-summary.md`. For probes you
+  run, apply the implementer's verdict-copy and manual-derivation rules to
+  your own measurements, reporting the quoted verdict or explicit verdict
+  absence and derivation evidence in `reproduction` and carrying the same
+  reported values into any associated finding. 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. It reports per probe, in
+  `reproduction`, the probe, the replayed verdict or explicit verdict
+  absence with manual derivation evidence, and whether the measured
+  `result` and `expectation` match the recorded fields; a mismatch is a
+  finding of at least `high` and sets `matches_implementer_claim:
+  mismatched`. The implementer legend renders into every implementer tier
+  and Codex developer instructions; the revised test suite exercises all
+  three cases and the corresponding transfer decisions. Evidence for task
+  cb4ff78f-b0cb-402e-8387-f996f676f964 is recorded in the astra-old-eight
+  run, T-005 implementation report.
+
+- A fix round now closes the defect class instead of the reported
+  instance. `assets/agents/implementer.md` (and every tier variant
+  rendered from it) states, for any round after a task's first, the
+  class-enumeration obligation (a search command plus its hit list in the
+  report, or a source-level closure with the reason) and a
+  one-mutation-probe-per-fixed-finding obligation. The implementer output
+  contract (`assets/skill/references/contracts.md`, mirrored in
+  `assets/agents/implementer.md`) gains a `class_closure` field (`kind:
+  enumerated | source | not_applicable` plus `command`, `sites` and
+  `closed: true | false`, with an unclosed site named in `risks` with the
+  reason); the subagent misfire rule now names the omission of
+  `class_closure` on any round after the task's first as a misfire, the
+  way it already names `mutation_probes` and `commits`.
+  `assets/agents/reviewer.md` gains the matching independent
+  class-enumeration obligation for round N+1 and now requires
+  `recurrence: repeated` whenever a finding's class matches an earlier
+  round's finding, even at a new site. `SKILL.md` step 8
+  (`references/evidence-and-probes.md`) now says the orchestrator halts
+  at the first `recurrence: repeated` finding whose `introduced_by_delta`
+  is `yes` or `unknown` and names split or redesign in `03-decisions.md`
+  before any further implementer spawn; the Round-2 halt rule paragraph in
+  `references/review-and-recovery.md` cross-references that halt at the
+  same scope, both sites pinned through one shared test constant.
+  `assets/templates/04-implementation-summary.md`
+  gains a Class Closure row per fix round (class, enumeration command,
+  sites, closure kind). Anchored by two observed batches: batch 48 saw 8
+  repeated findings of 32 review rounds, and batch 51 saw 13
+  repeated-finding mentions across 22 rounds, 7 of those rounds
+  attributable to case-level fixes or inert fixes rather than a closed
+  class. Anchored by an observed run: this fix-round contract was itself
+  applied in the fix rounds of the run that shipped it, before merge.
+
+## [0.38.1] - 2026-09-20
+
+- Repository lint, not shipped in the package: rule 1 of
+  `scripts/check-release-changelogs.mjs` now accepts hyphens in
+  build-metadata identifiers, so `1.0.0+build-1` can match its release
+  heading. Build metadata follows SemVer's identifier grammar: underscores
+  remain invalid, and metadata remains excluded from precedence comparison.
+- The default-mode sequence qualifiers now cover their planning steps and
+  point to the Run mode section of run-state and harness.
+
 ## [0.38.0] - 2026-09-19
 
 - A run now declares a run mode. `assets/templates/00-goal.md` carries
@@ -98,27 +209,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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;
+  delegation. Step 7 now says: "For a review round whose entire delta contains only explanatory documentation, comments, or citations and contains no source- or test-file edits and no semantic change to executable commands, configuration, policy, instructions, or behavior, 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 review round that touches an instruction, policy, template or prompt file (for example a SKILL.md instruction) keeps the general default, whatever the file type, and the minimums named above are unaffected";
   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
+  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 pinned; one left unpinned is named in the criterion with the reason it is not load-bearing." A reviewer briefing
+  bounds the prose mutant space to that list, and "When the briefing
+  bounds the
+  prose mutant space to a claim list, respect that bound and put scope notes in
+  `residual_risks`, unless an unlisted sentence is shown to be load-bearing."
+  Copies are bound to the normative site by one shared test constant, and: "Cap
+  test-adequacy review rounds on the change at two." "A test-adequacy review
+  round is one whose returned findings are all `tests` findings of severity
+  `low` or `medium` about pin gaps on the pinned prose; a round returning any
+  other finding is an ordinary round outside the cap." "The cap changes neither
+  the Round-2 halt rule, the Review-round escalation budget nor the
+  Fix-regression decision point: a test-adequacy review round still counts as a
+  negative round where it is one." It exempts semantic findings and leaves the
+  review gate as it is. 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

package/assets/agents/implementer.md

@@ -87,6 +87,23 @@ Rules:
   `result` alone is not: report it as such (`result` `survived` or
   `not_applicable` with the reason) and resolve it before the next
   reviewer spawn.
+- On any round after the task's first, when the round fixes a review
+  finding, enumerate the defect's class before returning: run a search
+  command for the pattern the finding's fix addresses and list every hit
+  in the report, or state a source-level closure (the fix removes the
+  pattern at its one source, closing the whole class without a search)
+  and say why in `summary`. Report the result in the output contract's
+  `class_closure` field: `kind: enumerated | source | not_applicable`
+  (`not_applicable` only on the task's first round, when there is no
+  review finding yet to fix), the search `command` that produced the hit
+  list (empty when `kind` is not `enumerated`), and the `sites` list of
+  every hit found (empty when `kind` is not `enumerated`), and `closed:
+  true` when every site the round found (by search or by source-level
+  closure) is fixed this round, `false` when a found site is not; name an unclosed site in `risks` with
+  the reason. On the task's first round `kind` is `not_applicable`, `command` and `sites` are empty,
+  and `closed` is `true`, since no site was found to leave open. Run one mutation probe per review
+  finding fixed in the round, in addition to any probe the assignment names, and report each one in
+  `mutation_probes`. A fix-round return without `class_closure` is a misfire per the misfire rule.
 - A persisted probe-plan reference may stand in for a repeated inline mutant
   definition when it resolves to a path plus immutable revision or hash and the
   mutant locator/index. Resolve it before running; a missing, stale, or
@@ -96,14 +113,33 @@ Rules:
   Never rewrite a prior plan for new code; record intentional supersession and
   rationale in run state before using a replacement.
 - When a verify runner is available, run it for the checks the acceptance
-  criteria name and report its summary under `tests.executed`; when a
-  mutation-probe runner is available, run the named probes through it and
-  copy its fields into `mutation_probes`; when the runner reports a
-  probe's mutant record (`file`, `anchor`, `before`, `after`) separately
+  criteria name and report its summary under `tests.executed`. When a
+  mutation-probe runner is available, run the named probes through it and copy
+  every supplied `result` and `expectation` verbatim into `mutation_probes`,
+  never substituting your interpretation of its test output. When the
+  runner reports a probe's mutant record (`file`, `anchor`, `before`,
+  `after`) separately
   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. `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.
+  `mutation_probes` sub-fields. `result: killed` means the probe's test
+  command reacted to the mutant under the runner's pass predicate, or the
+  test pass predicate declared in the task assignment or probe plan when
+  no runner supplies a verdict; `survived` means it did not. `expectation:
+  met` means the measured result matches the expected result declared in
+  the task assignment or probe plan, and `violated` means it does not;
+  both fields are `not_applicable` when no result was measured. Quote each
+  supplied verdict in `tests.executed`; when it supplies only `result`,
+  derive `expectation` from the expected result declared in the task
+  assignment or probe plan, and identify that declaration and derivation
+  there. When no machine-readable verdict is available, state that
+  explicitly in `tests.executed`, identify the declared test pass
+  predicate and expected result, and quote the observed baseline and
+  mutant outcomes. Derive `result` from those observations only when the
+  baseline passed, mutant application was verified, and the mutant test
+  completed under the same command and predicate; derive `expectation` by
+  comparing that result with the declared expected result, and label both
+  derivations as manual.
 - 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
@@ -210,6 +246,12 @@ mutation_probes:
     reason: ""
     restored_verified: ""
     replayed: false | true
+class_closure:
+  kind: enumerated | source | not_applicable
+  command: ""
+  sites:
+    - ""
+  closed: true | false
 risks:
   - severity: low | medium | high
     description: ""

package/assets/agents/reviewer.md

@@ -77,7 +77,7 @@ Check, at minimum:
   calibrated to sit inside the output's own run-to-run noise (timing digits,
   temporary-directory names) is not a regression test; the fix is to pin
   the argument under test in-process, or assert the actual contract (a
-  bound, or the presence of a warning), never a byte ceiling.
+  bound, or the presence of a warning), never a byte ceiling. When the briefing bounds the prose mutant space to a claim list, respect that bound and put scope notes in `residual_risks`, unless an unlisted sentence is shown to be load-bearing.
 - Maintainability: naming, dead code, needless abstraction, doc drift.
 - Placement: does the change add org-, machine-, or point-in-time-bound
   evidence (dates, sample sizes, task ids, home paths, incident tallies) to a
@@ -87,8 +87,21 @@ Check, at minimum:
 - Recurrence: when the briefing tells you this is not the task's first
   review round, classify each finding as `new` or `repeated` against the
   earlier rounds you were told about; on a first round every finding is
-  `new` by definition. The orchestrator uses this to detect the
-  review-round escalation budget's trigger. Delta attribution: classify every finding as `introduced_by_delta: yes | no | unknown`; set `no` only after naming the base build and replaying the same reproduction in `reproduction`, and record it in `05-review-findings.md` through the ordinary gate rather than bounded-round halt/escalation guidance (yes/unknown only).
+  `new` by definition. Class match, not site match, decides this: set
+  `repeated` whenever a finding's defect class matches an earlier round's
+  finding, even when this instance sits at a site the earlier round never
+  touched. On any round after the task's first, run your own
+  class-enumeration search independent of the implementer's
+  `class_closure` report: search for the pattern the earlier finding's fix
+  addressed, and compare what your own search returns against the
+  implementer's `class_closure.sites` list (or its `source` closure
+  reason); a site your search finds that the implementer's report omits
+  is itself a finding, classified under the ordinary severity gate by
+  the underlying defect's own severity, not by a fixed floor. In run
+  mode `single` there is no separate implementer `class_closure` report
+  to compare against; compare your search's hits against the Class Closure row of
+  `04-implementation-summary.md` plus its Risks / Notes section instead. The orchestrator
+  uses this to detect the review-round escalation budget's trigger. Delta attribution: classify every finding as `introduced_by_delta: yes | no | unknown`; set `no` only after naming the base build and replaying the same reproduction in `reproduction`, and record it in `05-review-findings.md` through the ordinary gate rather than bounded-round halt/escalation guidance (yes/unknown only).
 - GitHub Actions shell replay: for any diff that adds or changes a GitHub
   Actions `run:` step, replay it yourself under the shell the step actually
   runs: `bash --noprofile --norc -eo pipefail` when `shell: bash` is set on
@@ -155,15 +168,35 @@ Rules:
   the exact commit and the run count, since branch coverage can vary
   between runs of the same commit.
 - When a mutation-probe runner is available in the session, run probes
-  through it instead of editing files by hand, and carry its result fields
-  into your findings and `reproduction`; when a verify runner is available,
-  read its summary before opening full logs.
+  through it instead of editing files by hand. For probes you run, apply the
+  implementer's verdict-copy and manual-derivation rules to your own
+  measurements, reporting the quoted verdict or explicit verdict absence and
+  derivation evidence in `reproduction` and carrying the same reported values
+  into any associated finding. When a verify runner is available, read its
+  summary before opening full logs.
 - A reviewer briefing may identify a replayed probe through a resolved
   immutable probe-plan reference (path plus revision/hash and mutant
   locator/index) rather than repeat its inline definition. Verify the plan and
   result bind the checked state, cwd, attempt, expectation, application, and
   restoration; a plan alone, stale reference, or unresolved reference is not
-  evidence. Legacy inline probe reports remain valid. When the briefing names run mode `single`, the orchestrator implemented the change itself and nobody has cross-checked its probe evidence: replay every named orchestrator probe, where named means the briefing gives its full definition or a resolved immutable plan-and-result reference (in a scratch copy or an isolating probe runner, never in the reviewed tree), and state in `reproduction`, per probe, the replayed verdict and whether it matches the recorded `result` and `expectation`. Do not skip a named probe in that mode, under any `review_method`; any mismatch also sets `matches_implementer_claim: mismatched`. A mismatch is a finding of at least `high`; a probe given only by id is `not_applicable` and is missing evidence, not a pass, and so is a briefing in that mode that names no probe. Without that mode line in the briefing this obligation does not exist.
+  evidence. Legacy inline probe reports remain valid.
+  When the briefing names run mode `single`, the orchestrator implemented
+  the change itself
+  and nobody has cross-checked its probe evidence: replay every named
+  orchestrator probe, where named means the briefing gives its full
+  definition or a resolved immutable plan-and-result reference (in a
+  scratch copy or an isolating probe runner, never in the reviewed tree).
+  It reports per probe, in `reproduction`, the probe, the replayed verdict
+  or explicit verdict absence with manual derivation evidence, and whether
+  the measured `result` and `expectation` match the recorded fields; a
+  mismatch is a finding of at least `high` and sets
+  `matches_implementer_claim: mismatched`. Do not skip a named probe in
+  that mode, under any `review_method`; any mismatch also sets
+  `matches_implementer_claim: mismatched`. A mismatch is a finding of at
+  least `high`; a probe given only by id is `not_applicable` and is
+  missing evidence, not a pass, and so is a briefing in that mode that
+  names no probe. Without that mode line in the briefing this obligation
+  does not exist.
 
 Return exactly this structure as your final output, nothing else:
 ```yaml

package/assets/agents-md-section.md

@@ -1,12 +1,14 @@
 <!-- orchestrator-workflow:begin -->
 ## Agentic Coding Workflow
 
-This repository uses an orchestrator-led agent workflow, installed and updated by
+This repository uses an orchestrator-led agent workflow, installed and
+updated by
 [orchestrator-workflow](https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow).
 
 The primary agent acts as the orchestrator. It owns the goal, planning, task
-validation, delegation, final acceptance, and the operator handoff. Non-trivial
-review is delegated to a narrow subagent; which agent implements non-trivial work follows from the run mode (Core rules). The full procedure
+validation, delegation, final acceptance, and the operator handoff.
+Non-trivial review is delegated to a narrow subagent; which agent implements
+non-trivial work follows from the run mode (Core rules). The full procedure
 and the subagent I/O contracts live in the `orchestrator-workflow` skill.
 
 ### Core rules
@@ -21,10 +23,14 @@ and the subagent I/O contracts live in the `orchestrator-workflow` skill.
   inline with the same read-only discipline instead.
 - The orchestrator plans features itself. It may delegate task slicing, but it
   validates the sliced tasks before implementation starts.
-- Non-trivial implementation follows the run mode recorded in `00-goal.md`. `delegated`, the default, sends it to narrow implementer subagents, one task
-  per subagent; in `single` the orchestrator implements one coherent workstream itself; `batch` runs implementers in parallel worktrees. The skill's Run mode section defines the modes and how to choose one.
+- Non-trivial implementation follows the run mode recorded in `00-goal.md`.
+  `delegated`, the default, sends it to narrow implementer subagents, one
+  task per subagent; in `single` the orchestrator implements one coherent
+  workstream itself; `batch` runs implementers in parallel worktrees. The
+  skill's Run mode section defines the modes and how to choose one.
 - Non-trivial review goes to a separate reviewer subagent (see Scaling
-  delegation). Review itself is never skipped, in any run mode, not even for docs or bulk
+  delegation). Review itself is never skipped, in any run mode, not even for
+  docs or bulk
   changes.
 - Final acceptance and the final answer to the operator stay with the
   orchestrator.
@@ -41,7 +47,8 @@ default, not a ritual.
   solution; skip it when the change is well understood. Under a `minimal`
   profile there is no explorer subagent to spawn; run this step inline
   instead.
-- Slicing and, in run modes `delegated` and `batch`, implementer subagents are for non-trivial work: multiple files,
+- Slicing and, in run modes `delegated` and `batch`, implementer subagents are
+  for non-trivial work: multiple files,
   real logic, or anything that benefits from decomposition or a fresh context.
   Under a `minimal` profile there is no task-slicer subagent; the orchestrator
   slices inline with the same contract.
@@ -55,7 +62,9 @@ default, not a ritual.
   scripts, hand-edited lockfiles, cross-major overrides, or anything the
   operator flags high-risk; `normal` fits only docs, renames, or batch
   cosmetics; `rigorous` is the default otherwise. Never pair `adversarial`
-  with the `-medium` reviewer tier; tiers themselves are unchanged. A docs-only delta has its own review default; the skill's Delegate review step states it.
+  with the `-medium` reviewer tier; tiers themselves are unchanged. A
+  docs-only delta has its own review default; the skill's Delegate review step
+  states it.
 - When tier variants are installed (manifest `tiers: true`), the orchestrator
   picks the effort tier per task by complexity and risk, at its own judgment.
   The unsuffixed default subagent is the normal case; `-high`/`-xhigh` fit
@@ -111,7 +120,8 @@ trivial change.
 - Medium and low findings are addressed or consciously accepted at the
   orchestrator's judgment.
 - After independent review, the orchestrator may close a docs-only delta
-  without another reviewer round only when its entire unreviewed delta is explanatory
+  without another reviewer round only when its entire unreviewed delta is
+  explanatory
   documentation, comments, or citations; has no source- or test-file edits or
   semantic changes to executable commands, configuration, policy,
   instructions, or behavior; and closes only low/medium documentation or
@@ -128,9 +138,13 @@ trivial change.
   the exhausted tier path falls straight to the merge-hold), or an
   operator merge-hold, and adds a row (task, choice, reason) to
   `03-decisions.md`'s Review-round escalation table, then sets the
-  `review-round-escalation` marker to the most recent choice. A negative round
+  `review-round-escalation` marker to the most recent choice.
+  In `single`, tier/model escalation requires a recorded switch to `delegated`.
+  A negative round
   has an `acceptance_recommendation` of `fix_required` or `reject`; a misfired
-  review is not a round. A negative round counts only with at least one introduced_by_delta yes/unknown finding; no stays ordinary gate. Which of the three is
+  review is not a round. A negative round counts only with at least one
+  introduced_by_delta yes/unknown finding; no stays ordinary gate. Which of the
+  three is
   picked is judgment; that one is picked and recorded is not. Escalating
   never substitutes for a review round and comes in addition to the halt
   rule's split-or-redesign response, not instead of it.
@@ -175,7 +189,8 @@ Workflow state lives under `.ai/`:
   routing selections.
 - Every worktree a run touches carries a `.ai/run` pointer (absolute path of
   the run directory, gitignored) and `00-goal.md` carries one
-  `run-base[<repo-basename>]` marker per repository for multi-repo runs, next to the run's `mode` marker.
+  `run-base[<repo-basename>]` marker per repository for multi-repo runs, next
+  to the run's `mode` marker.
 
 ### Models
 

package/assets/skill/SKILL.md

@@ -53,7 +53,7 @@ role definitions where available rather than improvising prompts.
    tool over raw grep. Otherwise proceed.
 3. **Plan and slice.** Fill `01-plan.md` and `02-tasks.md`; validate narrow,
    ordered, testable tasks and their allowed/forbidden changes. Read
-   [contracts](references/contracts.md). Steps 3 and 4 are written for the default run mode; the Run mode section says what changes in the other two.
+   [contracts](references/contracts.md). Steps 3 and 4 are written for the default run mode; the Run mode section of run-state and harness says what changes in the other two modes.
 4. **Implement and prove.** Read the detailed workflow before delegating each
    implementer one narrow task and resolve its repository-bound verification
    set before authorizing commands,

package/assets/skill/references/contracts.md

@@ -113,6 +113,12 @@ mutation_probes:
     reason: ""
     restored_verified: ""
     replayed: false | true
+class_closure:
+  kind: enumerated | source | not_applicable
+  command: ""
+  sites:
+    - ""
+  closed: true | false
 risks:
   - severity: low | medium | high
     description: ""
@@ -125,8 +131,27 @@ 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. `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.
+commit reporting, follow the installed 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 pass predicate, or the
+test pass predicate declared in the task assignment or probe plan when no
+runner supplies a verdict; `survived` means it did not. `expectation: met`
+means the measured result matches the expected result declared in the task
+assignment or probe plan, and `violated` means it does not; both fields
+are `not_applicable` when no result was measured. When a mutation-probe
+runner is available, run the named probes through it and copy every
+supplied `result` and `expectation` verbatim into `mutation_probes`, never
+substituting your interpretation of its test output. Quote each supplied
+verdict in `tests.executed`; when it supplies only `result`, derive
+`expectation` from the expected result declared in the task assignment or
+probe plan, and identify that declaration and derivation there. When no
+machine-readable verdict is available, state that explicitly in
+`tests.executed`, identify the declared test pass predicate and expected
+result, and quote the observed baseline and mutant outcomes. Derive
+`result` from those observations only when the baseline passed, mutant
+application was verified, and the mutant test completed under the same
+command and predicate; derive `expectation` by comparing that result with
+the declared expected result, and label both derivations as manual.
 
 ## Reviewer output contract
 

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

@@ -40,7 +40,7 @@ directory and the subagents.
    contract instead.
 3. **Plan.** Fill `01-plan.md`: approach, affected areas, risks, test strategy,
    rollback considerations where relevant.
-4. **Slice tasks.** (Steps 4 to 6 are written for the default run mode; Run mode in run-state and harness says what changes in the other two.) For non-trivial changes, fill `02-tasks.md`. Delegate to
+4. **Slice tasks.** (Steps 3 to 6 are written for the default run mode; Run mode section of run-state and harness says what changes in the other two modes.) For non-trivial changes, fill `02-tasks.md`. Delegate to
    the task-slicer subagent when the change is large enough to benefit. Each
    explicitly adopted v1 task carries: id, title, goal, acceptance baseline, acceptance criteria,
    relevant files, relevant docs, constraints, suggested tests, allowed changes, forbidden
@@ -112,7 +112,21 @@ 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. 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
+   subsection, with the round it was named in. Before transferring a probe
+   row, compare each copied field with the quoted verdict and each derived
+   field with its stated declaration and evidence. An explicit absence of
+   a machine-readable verdict requires the manual comparison, not resupply
+   of a nonexistent verdict. On a mismatch or missing required evidence,
+   obtain corrected evidence from the implementer or rerun the probe in
+   isolation, record the action in `03-decisions.md`, and keep the row
+   blocked from transfer until the comparison succeeds; if the evidence
+   cannot be obtained, record the unresolved proof rather than repeatedly
+   requesting an unavailable verdict. Never invent a verdict, override a
+   supplied field, or fill an unsupported derivation. Apply the same
+   evidence reporting and comparison to probes you run yourself before
+   recording their rows in `04-implementation-summary.md`. 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
@@ -152,7 +166,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. 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
+   them; tiers themselves are unchanged by this axis. For a review round whose entire delta contains only explanatory documentation, comments, or citations and contains no source- or test-file edits and no semantic change to executable commands, configuration, policy, instructions, or behavior, 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 (for example a SKILL.md instruction) 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
@@ -198,8 +212,25 @@ directory and the subagents.
    not merely their id; a probe recorded with only an id and no definition
    cannot be skipped this way and is `not_applicable`. The reviewer may
    then skip re-running the ones named by definition.
-   The reviewer output contract itself is unchanged. In run mode `single` that skip permission does not apply: nobody but the orchestrator has seen its probe evidence. A probe counts as named when the briefing gives its full definition or a resolved immutable plan-and-result reference; an id alone does not name a probe. The orchestrator records every probe it ran in one of those two forms in `04-implementation-summary.md` before requesting review, the reviewer briefing states the run mode and names each of those probes, and the reviewer must replay every named orchestrator probe, through the probe runner when one is available and never in the reviewed tree. It reports per probe, in `reproduction`, the probe, the replayed runner verdict, and whether that verdict matches the recorded `result` and `expectation`; a mismatch is a finding of at least `high` and sets `matches_implementer_claim: mismatched`. A probe given only by id is `not_applicable` and counts as missing evidence, not as a pass, and so does a `single` briefing that names no probe at all. Never run mutation probes
-   in place against a worktree a reviewer subagent is concurrently reviewing;
+   The reviewer output contract itself is unchanged. In run mode `single`
+   that skip permission does not apply: nobody but the orchestrator has
+   seen its probe evidence. A probe counts as named when the briefing
+   gives its full definition or a resolved immutable plan-and-result
+   reference; an id alone does not name a probe. The orchestrator records
+   every probe it ran in one of those two forms in
+   `04-implementation-summary.md` before requesting review, the reviewer
+   briefing states the run mode and names each of those probes, and the
+   reviewer must replay every named orchestrator probe, through the probe
+   runner when one is available and never in the reviewed tree. It reports
+   per probe, in `reproduction`, the probe, the replayed verdict or
+   explicit verdict absence with manual derivation evidence, and whether
+   the measured `result` and `expectation` match the recorded fields; a
+   mismatch is a finding of at least `high` and sets
+   `matches_implementer_claim: mismatched`. A probe given only by id is
+   `not_applicable` and counts as missing evidence, not as a pass, and so
+   does a `single` briefing that names no probe at all. Never run mutation
+   probes in place against a worktree a reviewer subagent is concurrently
+   reviewing;
    isolate the probe in a separate worktree or wait until the reviewer has
    returned before probing that tree again. For an explicitly adopted v1 run,
    ask the reviewer to compare the frozen delegated criteria with the
@@ -222,9 +253,11 @@ directory and the subagents.
    documentation or maintainability findings. This option never closes a
    high/critical or other ineligible finding. Record the concrete verification
    in a `05-review-findings.md` row, keeping its Severity and Decision headers
-   unchanged and setting Decision to `accepted`. Watch for the round-2
-   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`
+   unchanged and setting Decision to `accepted`. Halt at the first
+   `recurrence: repeated` finding whose class a previous round's fix already addressed and
+   whose `introduced_by_delta` is `yes` or `unknown` (see Round-2 halt rule below): before any
+   further implementer spawn on that task, name split or redesign in `03-decisions.md`. 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. 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
@@ -305,7 +338,8 @@ is an honest failure, not a misfire. `skip`, `acknowledged`, `limitation`, and
 inconclusive results remain non-passes and cannot be silently accepted. When a
 repository has `docs/okf/`, include its bundle check in every set regardless of
 which files changed. This is a documented convention, not an OW execution
-engine or runtime schema validator.
+engine or runtime schema validator. 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.
 
 # Persisted probe plans
 

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

@@ -7,7 +7,8 @@ A subagent return is a misfire, not evidence, when its output does not parse
 against its role's output contract, including an implementer return that
 omits the `mutation_probes` field even though the task assignment named
 mutation probes to run, or that omits the `commits` field even though the
-task assignment asked for a commit. When a subagent returns near-instantly
+task assignment asked for a commit, or that omits the `class_closure`
+field on any round after the task's first. When a subagent returns near-instantly
 with no tool activity, treat that as a misfire signal rather than proof:
 check the output against the contract with extra suspicion, and accept it
 only if it is contract-valid and the assignment was answerable from the
@@ -44,7 +45,11 @@ cases. Ship the healthy half on its own verification, and refile the
 removed half as its own task carrying the measurement history that led to
 the split. Acceptance criteria that cannot be satisfied this way go to the
 operator as a merge-hold (hold the change unmerged and hand the decision to
-the operator).
+the operator). Step 8 of the detailed workflow states the operational
+halt: stop at the first `recurrence: repeated` finding whose class a
+previous round's fix already addressed and whose `introduced_by_delta`
+is `yes` or `unknown`, before any further implementer spawn on the
+task, and record the split-or-redesign decision in `03-decisions.md`.
 
 ## Review-round escalation budget
 
@@ -65,6 +70,9 @@ split-or-redesign response, not instead of it.
   option is exhausted; under a `full` profile the choice falls to the
   advisor spawn or the merge-hold, under a `minimal` profile (no advisor
   subagent to spawn) it falls straight to the merge-hold.
+  In `single`, tier/model escalation requires a recorded switch to `delegated`.
+  Apply the Run mode switch procedure before assigning the next attempt to an
+  implementer raised according to this tier/model escalation option.
 - **Advisor spawn** (where the advisor is installed, `full` profile):
   send the advisor subagent the question "redesign, split, or hold?" and
   weigh its recommendation before deciding.
@@ -124,8 +132,8 @@ the next unpinned sentence do not converge. For such a change:
 - 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.
+  adds or alters at that site is pinned; one left unpinned 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
@@ -133,16 +141,16 @@ the next unpinned sentence do not converge. For such a change:
 - 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
+  review round is one whose returned findings are all `tests` findings of
+  severity `low` or `medium` about pin gaps on the pinned prose; a round
+  returning any other 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
+Fix-regression decision point: a test-adequacy review 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

package/assets/templates/04-implementation-summary.md

@@ -92,6 +92,21 @@ where it lives in the row's own cell.
 |---|---|---|---|---|---|---|---|---|---|---|---|
 | <!-- round --> | <!-- mutant --> | <!-- file --> | <!-- anchor --> | <!-- before --> | <!-- after --> | <!-- verified_applied_via --> | <!-- result --> | <!-- expectation --> | <!-- reason --> | <!-- restored_verified --> | <!-- replayed --> |
 
+### Class Closure
+
+One row per fix round (any round after the task's first) that fixed a review
+finding: the defect class it closed, the search command run to enumerate other
+sites of that class (blank when `Closure Kind` is not `enumerated`), the sites
+the search found (blank when `Closure Kind` is not `enumerated`), and the
+closure kind (`enumerated | source`) the implementer reported in
+`class_closure`; `not_applicable` never appears in this table, since a row
+exists only for a round that fixed a finding, never for the task's first round.
+An unclosed site of the row's class is named in Risks / Notes with the reason.
+
+| Round | Class | Enumeration Command | Sites | Closure Kind |
+|---|---|---|---|---|
+| <!-- round --> | <!-- class --> | <!-- enumeration_command --> | <!-- sites --> | <!-- closure_kind --> |
+
 ### Optional Probe Plan and Result Index
 
 An optional runner-supported probe plan may be referenced here by relative

package/package.json

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