orchestrator-workflow 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,174 @@ 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

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

@@ -26,6 +26,11 @@ Check, at minimum:
   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:
 
@@ -73,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

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

@@ -185,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
@@ -194,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
@@ -320,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:
   - ""
@@ -336,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
@@ -478,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.24.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",