orchestrator-workflow 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,269 @@ All notable changes to `orchestrator-workflow` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.25.0] - 2026-08-27
+
+### Added
+
+- A "Review-round escalation budget" (`SKILL.md`, new section right after
+  the existing Round-2 halt rule): by the second round-2 halt signal on a
+  task, or its third `fix_required` review round, whichever comes first,
+  the orchestrator now picks one of three escalations, tier/model
+  escalation, an advisor spawn, or an operator merge-hold, instead of
+  running another round unaided, and records the choice in
+  `03-decisions.md`'s new Review-round escalation section (the
+  `review-round-escalation` marker: `n/a | tier_escalation | advisor |
+  merge_hold`, `n/a` a deliberately fail-open default since most runs
+  never trigger the budget at all, unlike the `TODO` fail-closed sentinel
+  the `solution-acceptance:` marker family uses). Which of the three is
+  picked stays a judgment call; only that one is picked and recorded is
+  now mandatory, and escalating never substitutes for a review round.
+  `agents-md-section.md` carries the same rule in short form. The
+  reviewer output contract (`SKILL.md` and `reviewer.md`) gained a
+  `recurrence: new | repeated` field per finding, and step 7 now has the
+  orchestrator name the review round number in the briefing when it is
+  not the task's first, so the reviewer can classify each finding against
+  the rounds it was told about instead of the orchestrator re-deriving
+  recurrence by hand. `03-decisions.md`'s new marker is a documented
+  convention only: nothing in this package's own code reads it today
+  (unlike the `solution-acceptance:` markers, which grounding-mcp's
+  run-completeness reader does parse); wiring it into that reader, if
+  wanted, is a follow-up in the consuming project, not part of this
+  change.
+
+  Evidence: agent-tasks d03af8f6 (pandora run
+  `.ai/runs/2026-08-26-open-pool-batch30`, a harness risk-gate deletion
+  arm) ran five implementer rounds on the same effort tier (rounds 1-5, the
+  default-tier implementer, Sonnet) before this rule existed; each reviewer
+  round found one new HIGH on the permissive side of the same detection layer
+  (first-segment matching, wrapper flags, xargs flags, a find-root premise
+  twice, xargs `-i`/append), and the Round-2 halt rule's split-or-redesign
+  response was applied three times (D-014, D-019, D-022/D-023) without ever
+  escalating tier, model, or to the advisor, and without a merge-hold. Only
+  after round 5 did the operator suggest a stronger model (D-024); round 6, on
+  Fable with the `-xhigh` variant, found and closed twelve further fail-open
+  classes in one round by its own 248-probe audit, and the following review
+  found only one remaining, a documentation-only medium. A same-run comparison
+  task, agent-tasks da823721, needed three rounds with one round-2 halt and
+  was accepted after it, well inside this budget. This is the first data
+  point relating implementer model strength to round count on a
+  permissive-security-parser class of task; the 2026-08-24 tier A/B (see
+  `[0.23.0]` below) measured only
+  `implementer-low` against the default tier on a different task shape,
+  not model strength, so whether a stronger model generally shortens
+  these rounds remains open.
+- A new `okf-anchor-guard` job in `.github/workflows/ci.yml` (this repo)
+  runs okf-kit's anchor check against `docs/okf` and fails the build (no
+  branch-protection change; master has no required checks today) when an
+  edit to `SKILL.md`, an agent template under `assets/agents/`,
+  `src/models.ts`, a `test/*.test.ts` file, any other `src/*.ts` module,
+  a run template under `assets/templates/`, or `assets/agents-md-section.md`
+  shifts a cited range out of the section or text an anchored bundle
+  citation names, instead of only the existing warn-only `okf-staleness.yml`
+  drift watch (which never blocks by design and stays untouched). Every
+  in-scope bundle citation into those source categories now carries a
+  string-form anchor (up from a first-round draft that review round 2
+  found had missed 44 bare, non-backtick-delimited citations in two of the
+  five docs/okf siblings; the citation parser was corrected to match
+  okf-kit's own backtick-optional shape; scope later widened from the
+  original four categories to every `src/*.ts` module and every
+  `assets/templates/*.md` plus `assets/agents-md-section.md`, agent-tasks
+  ca9d5048); the `CHANGELOG.md` citations still carry heading anchors from
+  the prior round (that mechanism is untouched, but every CHANGELOG entry
+  added above them, this one included, re-points all of them -- see
+  `docs/okf/log.md` for the live count and the re-point history, not
+  hand-copied here since it drifts with every CHANGELOG edit).
+- Every anchor now satisfies two mechanically-checked properties review
+  round 2 added (a first-round anchor sitting on a wide range's first line,
+  as 107 of 121 did, survives an insertion shorter than the range itself --
+  measured: round 1 had 46 SKILL.md-targeting anchors, and a 1-line
+  insertion near the top of SKILL.md left 24 of them silently green): (a)
+  the anchor text occurs on the LAST line of its cited range (ranges were
+  narrowed where needed to end on real content rather than a
+  blank/closing-brace line), and (b) it occurs at most 3 times in the
+  whole target file (23 first-round anchors used a too-common token, e.g.
+  `describe(`, and were
+  replaced). Two anchors were additionally re-pointed because the text
+  they carried did not match the claim their citing sentence made, not
+  just its mechanical position; see `docs/okf/log.md` for both. Pinned by
+  three new tests in `test/docs-consistency.test.ts` (version-pin
+  coverage extended to every `.github/workflows/*.yml` file, not just
+  `okf-staleness.yml`; the last-line/occurrence-cap rule, verified red
+  against the first-round anchors and green against this round's; and an
+  erosion brake asserting zero unanchored in-scope citations going
+  forward). `ci.yml`'s anchor-finding jq filter now matches any
+  `anchor-*`-tagged finding by pattern instead of four hardcoded rule
+  ids, guarded by a new self-test step that builds a throwaway fixture
+  bundle with one deliberately drifted anchored citation and requires the
+  filter to catch it before the real check runs.
+  `okf-kit check` reports the same 0 errors / 13 warnings / 22 notices
+  before and after this round's full anchor rewrite (0 anchor findings
+  either way; the 13 pre-existing warnings are unrelated
+  `install-fence-mechanics.md` short-form findings against `init.test.ts`
+  and `init.ts`). Differential mutation probe, replacing the first
+  round's single 27-finding number: inserting `k` dummy lines near the
+  top of SKILL.md, 52/52 (100%) of its unique cited ranges now produce a
+  finding at `k=1`; 51/52 (98%) at `k=2`, one named exception (a
+  same-block token collision, see `docs/okf/log.md`). A `package.json`
+  patch-version bump still leaves the anchor-finding count at 0,
+  confirming no false positive. Residual gaps named in `docs/okf/log.md`:
+  a content change inside a cited range that neither shifts its line
+  count nor disturbs the anchor text stays invisible to this check
+  (mechanical, never semantic, the same limit okf-kit's own README
+  documents), plus the one named same-block token collision above
+  (agent-tasks task 578f5bfd, review round 2; following the
+  anchored-citations feature itself, task 5c8013c0, and its release, task
+  c0effc67).
+
+### Changed
+
+- `docs/okf/subagent-contracts-superset.md`: rewrote its 22 sibling short-
+  form citations (21 initially, plus one missed and fixed this round) from
+  the parenthesized form (`(N-M)`) to the colon form (`, :N-M`) so
+  `citations-resolve` checks them again. Neither form was ever machine-
+  checked in a released `okf-kit`: the colon-form gate and the drop of
+  paren-form collection landed in the same `[Unreleased]` entry, so
+  "dropped" overstates it. Inserting this entry shifts every later line
+  number in this file, so any absolute-line `CHANGELOG.md` citation below
+  it breaks until re-pointed; this round re-points all sixteen such
+  citations across the three touched docs/okf siblings
+  (`subagent-contracts-superset.md`, `review-gate-and-waivers.md`,
+  `run-state-lifecycle-and-markers.md`), each checked against the
+  `## [x.y.z]` section its own sentence names, not against a byte-diff of a
+  moving base. `okf-kit check` against a repo build (not the published
+  package) reports 0 errors / 13 warnings / 22 notices; all 13 are
+  pre-existing `install-fence-mechanics.md` short-form findings unrelated
+  to this change, so the three touched docs carry no citations-resolve or
+  sources-fresh finding of their own (log.md records the fuller
+  sources-fresh investigation, since that count depends on this round's
+  commit shape, not on the citations themselves). Coverage holds only
+  against a repo build: CI's `okf-staleness.yml` still pins the published
+  `okf-kit@0.5.0`, which predates short-form colon resolution, so it
+  reports 0 short-form findings until that release ships (agent-tasks task
+  2e3e5f4b).
+- All sixteen `CHANGELOG.md` citations across the three `docs/okf` siblings
+  above now also carry a heading anchor (`` `CHANGELOG.md:N-M#x.y.z` ``, a
+  new `citations-resolve` form -- see okf-kit's own CHANGELOG for the
+  design), pinning each one to the release section its own sentence names
+  instead of only to a line range that a future top-of-file insertion can
+  silently shift into the wrong section. `okf-kit check` against a repo
+  build still reports the same 0 errors / 13 warnings / 22 notices as
+  above (all pre-existing, unrelated to this change); a mutation probe that
+  moved one migrated citation's range into its neighbouring release
+  section, and a second probe that inserted a dummy entry at the top of
+  this file (shifting every citation below it), were both caught by the
+  new anchor check and reverted (agent-tasks task 5c8013c0).
+
+### Corrections
+
+- Correction to the "Known limit of the pack" note in the 0.24.0 entry
+  below: this is not an `orchestrator-workflow` behavior change, it
+  documents a `slop-detector` fix. The 0.24.0 note described a known limit
+  of `placement-slop`, that an `allow` match suppressed every placement
+  rule on the line it matched, not just the marker span it was meant to
+  excuse. `slop-detector` has since fixed this (`placement.allow` is now
+  span-scoped, not line-wide). Consumer-visible effect: a config that
+  reported clean before can now report a `block`-severity finding (e.g.
+  `placement-slop/home-path`) when a home path, a date, or a tally phrase
+  shares a line with an allowed marker.
+
+## [0.24.0] - 2026-08-24
+
+### Changed
+
+- **Moved org-, machine-, and point-in-time-bound evidence out of the kit's
+  reusable instruction files; rule text is unchanged.** Public,
+  tool-agnostic kit files (`SKILL.md`, `agents-md-section.md`) now carry
+  rules and procedures only; the measurements, dates, sample sizes, task
+  ids, and incident tallies that used to sit inline are recorded here in
+  the changelog instead, with a one-line pointer left in prose.
+  - `SKILL.md` step 6 ("Delegate implementation"): the parenthetical
+    `(2026-08-24 A/B measurement, n=8: implementer-low reached accept a
+    median 320 seconds slower, p=0.016, with 9 high-plus-critical review
+    findings against 1 and 8 fix rounds against 1)` is now `(anchored by an
+    A/B measurement; see CHANGELOG 0.23.0)`. The full numbers already live
+    in the 0.23.0 entry below.
+  - `agents-md-section.md`'s Scaling delegation bullet: the paragraph
+    naming the A/B's `n=8`, the median slowdown, `p=0.016`, the
+    high-plus-critical finding count, the fix-round count, the Haiku 4.5
+    model detail, and agent-tasks task `7f38899d` is replaced by "This rule
+    is anchored by an A/B measurement; the data and the model caveat are
+    recorded in the orchestrator-workflow CHANGELOG (0.23.0)." Same data,
+    same 0.23.0 entry.
+  - `SKILL.md`'s "Subagent misfire rule": the incident tally `(four so
+    far)` and the whole reviewer/model-correlation passage ("So far this
+    signal has only been observed for the reviewer role ...", including the
+    0.21.0 advisor remark and the pointer to the per-role model
+    preferences) are removed. The rule itself (the signal definition, the
+    contract-parse and near-instant detection signals, the
+    resume-over-respawn preference and its reasoning, the respawn fallback,
+    the watchdog-stall exception, the `03-decisions.md` record requirement,
+    and "a misfired review is not a review") is unchanged. The removed
+    passage, verbatim, for the durable record: "Every incident of this
+    exact signal (a return within seconds, zero tool calls, harness or
+    system boilerplate instead of the output contract) whose outcome was
+    recorded (four so far) has resolved on the first resume attempt; fall
+    back to a fresh respawn only if the resume attempt itself misfires the
+    same way. So far this signal has only been observed for the reviewer
+    role, a role whose default model differs from explorer's,
+    task-slicer's, and implementer's (since 0.21.0 the advisor shares the
+    reviewer's default model too; the advisor has had no spawns yet, so it
+    contributes no evidence either way; see the per-role model
+    preferences); treat that correlation as an open lead worth watching as
+    more incidents accumulate, not as a confirmed cause." Of the four
+    resume outcomes recorded for that signal, three were on 2026-07-16 and
+    one was on 2026-07-20. The watchdog-stall exception's removed sentence,
+    also verbatim: "This resume-over-respawn preference does not extend to
+    a structurally different misfire class: a mid-run watchdog stall (the
+    subagent goes idle partway through a run rather than returning
+    near-instantly) did not resolve on resume in the one measured incident
+    of that class, it stalled a second time, and only a fresh, explicitly
+    constrained respawn produced a contract-valid review; treat a watchdog
+    stall as outside this preference."
+  - `SKILL.md`'s Run state paragraph: "see the grounding-mcp 0.6.0 docs for
+    the full consumer semantics" is now "see the consuming gate's
+    documentation (grounding-mcp) for the full consumer semantics", dropping
+    the pinned version number.
+
+### Added
+
+- **Reviewer placement check.** `reviewer.md`'s "Check, at minimum" list
+  gains a check for org-, machine-, or point-in-time-bound evidence (dates,
+  sample sizes, task ids, home paths, incident tallies) leaking into a
+  reusable instruction file (a skill, an agent prompt, an AGENTS.md
+  section, a template); the fix it recommends is moving the evidence to the
+  changelog, the run files, or the consuming workspace and leaving a
+  one-line pointer.
+- **Hand-off placement check.** `SKILL.md` step 9 ("Hand off") gains one
+  sentence for the orchestrator: check before handing off that no such
+  evidence was added to a reusable instruction file.
+- **`placement-guard` CI job.** A dedicated job in agent-dx's
+  `.github/workflows/ci.yml`, separate from the package matrix, builds
+  `slop-detector` and runs its opt-in `placement-slop` pack against the
+  monorepo's instruction files (`packages/orchestrator-workflow/assets/**`
+  and `packages/agentic-coding-playbook/**`, configured via the repo-root
+  `slop.config.yml`), failing on block-level violations.
+- **Root `slop.config.yml`.** Opts the `placement-slop` pack in for the CI
+  job, configures the `LanNguyenSi` org marker with `allow` entries for its
+  two legitimate repo links (`github.com/LanNguyenSi/`,
+  `raw.githubusercontent.com/LanNguyenSi/`, both anchored to a full
+  `https://` URL), widens the pack's instruction-file globs to cover this
+  package's `assets/` tree and the `agentic-coding-playbook` package, and
+  overrides `placement-slop/dated-evidence`, `placement-slop/tally-phrase`,
+  and `placement-slop/opaque-id` from their pack default of `warn` to
+  `block`, so the CI job actually fails on a leaked date, tally phrase, or
+  opaque id instead of only warning (a home path or an unlisted org marker
+  was already `block` by pack default). `packages/github-api-tool/SKILL.md`
+  carries two pre-existing dated examples that this severity change would
+  now block; it is `ignorePaths`-excluded pending a follow-up cleanup of
+  that unrelated package.
+  Known limit of the pack, unchanged here: an `allow` match suppresses
+  every placement rule on that line, so a home path or a date that shares
+  a line with an allowed repo URL is not reported; a span-scoped allow is
+  a slop-detector follow-up.
+
 ## [0.23.0] - 2026-08-24
 
 ### Changed

package/README.md

@@ -329,10 +329,9 @@ effort actually taking effect.
 The pin is also emitted unconditionally regardless of which model the role
 resolves to via `--models`, including a model with no effort support at all
 (e.g. `--models reviewer=haiku` still renders `model: haiku` followed by
-`effort: high`). A wire probe on 2026-08-19 (not re-measured for this doc)
-showed the Claude Code CLI silently drops the `effort:` parameter for Haiku
-4.5 rather than rejecting it: the value is ignored, not an install-time or
-run-time error.
+`effort: high`). On Haiku 4.5, which does not support the `effort`
+parameter, the harness ignores the pinned value rather than rejecting it
+(anchored by a measurement, see CHANGELOG 0.23.0).
 
 ## Ownership and re-runs
 

package/assets/agents/reviewer.md

@@ -21,6 +21,16 @@ Check, at minimum:
 - Test adequacy: are the new or changed behaviors covered, and would the new
   tests actually fail if the change were reverted? Flag inert tests.
 - 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
+  reusable instruction file (a skill, an agent prompt, an AGENTS.md section, a
+  template)? Report it; the fix is to move the evidence to the changelog, the
+  run files, or the consuming workspace and leave a one-line pointer.
+- 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.
 
 Rules:
 
@@ -68,6 +78,7 @@ findings:
     category: correctness | architecture | security | tests | maintainability | performance | docs
     description: ""
     suggested_fix: ""
+    recurrence: new | repeated
 acceptance_recommendation: accept | accept_with_notes | fix_required | reject
 missing_tests:
   - ""

package/assets/agents-md-section.md

@@ -61,25 +61,17 @@ default, not a ritual.
   those three excludes `implementer-low`, and the task runs on the unsuffixed
   implementer or higher, even when the change looks mechanical (a bugfix
   included); when it is unclear whether a criterion demands a run, exclude
-  `implementer-low`. This rule is anchored by an A/B measurement of
-  implementer-low as installed (Haiku 4.5) against the default implementer
-  (Sonnet 5, effort medium) (2026-08-24, n=8, identical tasks in both tiers,
-  blinded reviews, agent-tasks task 7f38899d): implementer-low reached accept
-  a median 320 seconds slower (p=0.016), drew 9 high-plus-critical review
-  findings against 1, and needed 8 fix rounds against 1. The A/B's
-  implementer-low ran on Haiku 4.5, which does not support the `effort`
-  parameter (per Anthropic's model reference), so the harness ignores the
-  pinned `effort: low` on that model; the measurement compared Haiku 4.5
-  without effort control against Sonnet 5 at `effort: medium`. For the
-  explorer and the task-slicer, a `-low` variant still suits narrowly scoped,
-  mechanical work; no equivalent measurement exists for those two roles, so
-  their rule is unchanged. Not every role gets every tier: `-xhigh` exists
-  only for the implementer, the reviewer, and the advisor. The reviewer's
-  downshift is `-medium` rather than `-low`, since its default already sits at
-  high. The advisor has no downshift at all: its default `high` is already its
-  only non-`-xhigh` tier. Spawn only variants that are actually installed.
-  Tier choice is a conscious decision, not a ritual; when unsure, use the
-  default.
+  `implementer-low`. This rule is anchored by an A/B measurement; the data and
+  the model caveat are recorded in the orchestrator-workflow CHANGELOG
+  (0.23.0). For the explorer and the task-slicer, a `-low` variant still suits
+  narrowly scoped, mechanical work; no equivalent measurement exists for those
+  two roles, so their rule is unchanged. Not every role gets every tier:
+  `-xhigh` exists only for the implementer, the reviewer, and the advisor. The
+  reviewer's downshift is `-medium` rather than `-low`, since its default
+  already sits at high. The advisor has no downshift at all: its default `high`
+  is already its only non-`-xhigh` tier. Spawn only variants that are actually
+  installed. Tier choice is a conscious decision, not a ritual; when unsure,
+  use the default.
 - Every unsuffixed default subagent carries its own pinned default effort
   baked into its own file, not inherited from the orchestrator session:
   medium for the explorer, the task-slicer, and the implementer; high for
@@ -111,6 +103,21 @@ trivial change.
   the Accepted Waivers section of `06-handoff.md`.
 - Medium and low findings are addressed or consciously accepted at the
   orchestrator's judgment.
+- Review-round escalation budget: by the second round-2 halt signal on a
+  task, or its third `fix_required` review round, whichever comes first,
+  the orchestrator picks one of tier/model escalation (raise the
+  implementer to at least `-xhigh` where installed, or to the strongest
+  model available, until that is exhausted), an advisor spawn (where the
+  advisor is installed, `full` profile only; under a `minimal` profile
+  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 counted
+  round is a completed reviewer return recommending `fix_required` or
+  `reject`; a misfired review is not a round. 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.
 
 ### Instruction trust boundary
 

package/assets/skill/SKILL.md

@@ -90,8 +90,8 @@ run-completeness readers, not an acceptance verdict, and it fails open:
 left as `TODO` it does not block anything, the reader just falls back to a
 tolerant day-granular date heuristic. The recorded base must resolve in the
 repo, be an ancestor of HEAD, and must not lie behind the fork point of the
-change (the merge-base with the remote default branch); see the
-grounding-mcp 0.6.0 docs for the full consumer semantics.
+change (the merge-base with the remote default branch); see the consuming
+gate's documentation (grounding-mcp) for the full consumer semantics.
 
 ## Workflow
 
@@ -147,10 +147,8 @@ directory and the subagents.
    task assignment names mutation probes to run; or the task slicer's
    `suggested_tests` came back non-empty. Any one of those three excludes
    `implementer-low`, even for a change that looks mechanical (a bugfix
-   included) (2026-08-24 A/B measurement, n=8: implementer-low reached accept
-   a median 320 seconds slower, p=0.016, with 9 high-plus-critical review
-   findings against 1 and 8 fix rounds against 1). When it is unclear
-   whether a criterion demands a run, exclude `implementer-low`. When a
+   included) (anchored by an A/B measurement; see CHANGELOG 0.23.0). When it is
+   unclear whether a criterion demands a run, exclude `implementer-low`. When a
    task's acceptance rests on a test that must fail without the change, name
    the mutation probes to run in the task assignment; the implementer reports
    each one in the output contract's `mutation_probes` field (apply the mutant
@@ -187,7 +185,12 @@ directory and the subagents.
    implementer's log — and record the method, sample size, and result against
    the implementer's claim in the reviewer output contract's `reproduction`
    field. This does not apply to deterministic checks (a single test run,
-   `tsc`, lint): only claims that could vary run to run trigger it.
+   `tsc`, lint): only claims that could vary run to run trigger it. When
+   this is not the task's first review round, name the round number in the
+   briefing; the reviewer marks each finding's `recurrence` as `new` or
+   `repeated` against the earlier rounds it was told about, which is what
+   lets the orchestrator detect the Review-round escalation budget's
+   trigger (see below) without re-deriving it by hand.
 8. **Decide acceptance.** Accept, request fixes, defer, or escalate to the
    operator. High or critical findings block acceptance until fixed or
    explicitly waived: critical findings require operator sign-off; high
@@ -196,7 +199,10 @@ directory and the subagents.
    all decisions and waivers in `03-decisions.md` and summarize waivers in
    the Accepted Waivers section of `06-handoff.md`. Watch for the round-2
    halt signal across repeated review-fix cycles (see Round-2 halt rule
-   below). At an advisor trigger (architectural uncertainty, conflicting
+   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
+   trigger (architectural uncertainty, conflicting
    requirements, a high-commitment fork among valid options, repeated
    implementation failures, a review deadlock, a high-risk decision), the
    orchestrator may spawn the advisor subagent before deciding; the advisor
@@ -213,7 +219,10 @@ directory and the subagents.
    validator when one is available (for example `okf-kit check`). Repos
    without a bundle are unaffected. Then fill `06-handoff.md` and report to the
    operator: what changed, why, how it was verified, known risks, accepted
-   waivers, suggested next step.
+   waivers, suggested next step. Before handing off, check that no org-,
+   machine-, or point-in-time-bound evidence was added to a reusable
+   instruction file; such evidence belongs in the changelog, the run files,
+   or the consuming workspace, with a pointer left behind.
 
 When finalizing `05-review-findings.md` and `06-handoff.md`, replace the `TODO`
 in each `<!-- solution-acceptance: ... = TODO -->` marker with the chosen enum
@@ -319,6 +328,7 @@ findings:
     category: correctness | architecture | security | tests | maintainability | performance | docs
     description: ""
     suggested_fix: ""
+    recurrence: new | repeated
 acceptance_recommendation: accept | accept_with_notes | fix_required | reject
 missing_tests:
   - ""
@@ -335,6 +345,12 @@ reproduction:
 When it is missing, the orchestrator asks the reviewer to resupply it
 instead of inferring one from the findings list.
 
+`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
+round every finding is `new` by definition. This is what feeds the
+Review-round escalation budget's trigger.
+
 ## Task slicer output contract
 
 ```yaml
@@ -451,22 +467,14 @@ explicitly repeats the original assignment rather than a generic retry,
 since resume keeps the subagent's prior turn in context while a fresh spawn
 starts cold and risks the same misfire again. Every incident of this exact
 signal (a return within seconds, zero tool calls, harness or system
-boilerplate instead of the output contract) whose outcome was recorded
-(four so far) has resolved on the first resume attempt; fall back to a
-fresh respawn only if the resume attempt itself misfires the same way. So
-far this signal has only been observed for the reviewer role, a role whose
-default model differs from explorer's, task-slicer's, and implementer's
-(since 0.21.0 the advisor shares the reviewer's default model too; the
-advisor has had no spawns yet, so it contributes no evidence either way; see
-the per-role model preferences); treat that correlation as an open lead
-worth watching as more incidents accumulate, not as a confirmed cause. This
-resume-over-respawn preference does not extend to a structurally different
-misfire class: a mid-run watchdog stall (the subagent goes idle partway
-through a run rather
-than returning near-instantly) did not resolve on resume in the one
-measured incident of that class, it stalled a second time, and only a
-fresh, explicitly constrained respawn produced a contract-valid review;
-treat a watchdog stall as outside this preference. Record every misfire in
+boilerplate instead of the output contract) whose outcome was recorded has
+resolved on the first resume attempt; fall back to a fresh respawn only if
+the resume attempt itself misfires the same way. This resume-over-respawn
+preference does not extend to a structurally different misfire class: a
+mid-run watchdog stall (the subagent goes idle partway through a run rather
+than returning near-instantly) did not resolve on resume; only a fresh,
+explicitly constrained respawn produced a contract-valid review; treat a
+watchdog stall as outside this preference. Record every misfire in
 `03-decisions.md`. This matters most for review: a misfired review is not a
 review and never satisfies the review gate, since review is never skipped.
 
@@ -485,6 +493,44 @@ 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).
 
+## Review-round escalation budget
+
+The Round-2 halt rule above stops the first time a defect class recurs
+within one task. This rule puts a budget on the whole task, across halts
+and across repeated review rounds, so effort does not keep accumulating
+unaided: by the second round-2 halt signal on the same task, or by the
+third `fix_required` review round on the same task, whichever comes
+first, choose one of three escalations instead of running another round
+the same way. A counted round is a completed reviewer return whose
+`acceptance_recommendation` is `fix_required` or `reject`; a misfired
+review is not a round (see Subagent misfire rule); the escalation is
+chosen once the third such round has returned, before the next attempt
+starts. The escalation is chosen in addition to the halt rule's
+split-or-redesign response, not instead of it.
+
+- **Tier or model escalation**: raise the implementer to at least
+  `-xhigh` where that variant is installed, or to the strongest model
+  available in this environment. When it already runs at both, this
+  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.
+- **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.
+- **Merge-hold**: hold the change unmerged and hand the decision to the
+  operator.
+
+Judgment governs which of the three to pick; only that one is chosen and
+recorded is mandatory. Add a row (task, choice, reason) to
+`03-decisions.md`'s Review-round escalation table, the record of the
+decision, and set the `review-round-escalation` marker to the most recent
+choice (a reader shortcut derived from that table, one of `n/a |
+tier_escalation | advisor | merge_hold`). Escalating does not replace a
+review round: whichever option is chosen, the next attempt still goes
+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.
+
 ## Final acceptance rule
 
 Subagents provide evidence. The orchestrator decides. The operator receives

package/assets/templates/03-decisions.md

@@ -3,3 +3,16 @@
 | Date | Decision | Reason | Consequences |
 |---|---|---|---|
 | YYYY-MM-DD | <!-- decision --> | <!-- reason --> | <!-- consequences --> |
+
+## Review-round escalation
+
+<!-- One row per task that triggers the Review-round escalation budget in SKILL.md: the second round-2 halt signal or the third fix_required review round on that task. A run carries multiple tasks, so this table can carry multiple rows. Leave the single placeholder row as n/a when no task in this run has triggered the budget. -->
+
+| Task | Choice | Reason |
+|---|---|---|
+| n/a | n/a | n/a |
+
+<!-- Choice is one of: n/a | tier_escalation | advisor | merge_hold -->
+
+<!-- review-round-escalation: choice = n/a -->
+<!-- Reader marker: the most recent choice recorded in this run's table above, kept for readers that scan for a single marker rather than the table. One of: n/a | tier_escalation | advisor | merge_hold -->

package/assets/templates/05-review-findings.md

@@ -28,3 +28,6 @@ accept | accept_with_notes | fix_required | reject
 <!-- solution-acceptance: acceptance-recommendation = TODO -->
 
 <!-- Reproduction note: when a finding rests on empirical or probabilistic evidence (flake rates, benchmarks, "n runs green", performance/timing numbers), record the reviewer's independent reproduction (method, sample size, result vs. the implementer's claim) in the reviewer output contract's `reproduction` field (SKILL.md step 7). Deterministic checks (a single test run, tsc, lint) do not require it. -->
+
+<!-- Recurrence note: each finding in the reviewer output contract also carries a `recurrence` field (new or repeated), letting the orchestrator read the Review-round escalation budget's trigger (SKILL.md, Review-round escalation budget) off the reviewer's own return instead of reconstructing it by hand. A repeated finding here is what feeds that budget's round count. -->
+

package/package.json

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