orchestrator-workflow 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,119 @@ 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).
 
+## [0.18.0] - 2026-08-18
+
+### Changed
+
+- Extends the Subagent misfire rule (`SKILL.md`) and hardens the installed
+  reviewer prompt, both docs/prompt-only, after two further sessions
+  (2026-07-19, 2026-07-20) reproduced the same near-instant, no-tool-activity
+  reviewer misfire the rule was originally written for in 0.11.0: a
+  first-spawn reviewer returned within seconds, zero tool calls, harness or
+  system boilerplate instead of the output contract. In the 2026-07-20
+  session, a resume on the same subagent with the assignment explicitly
+  repeated produced a full, contract-valid review; the 2026-07-19 session's
+  resume outcome was not recorded. Explorer and implementer first spawns
+  never misfired in either session.
+  - **Concrete resume-over-respawn workaround.** The rule previously said
+    only "resume or respawn," leaving the choice and the resume mechanics
+    unstated. It now names, for this specific signal, resume over a fresh
+    respawn as the preferred response, states the mechanic (repeat the
+    original assignment explicitly, not a generic retry, since resume keeps
+    the subagent's prior context while a fresh spawn starts cold), and
+    scopes the fallback to a fresh respawn to the case where the resume
+    attempt itself misfires the same way. This preference is scoped to the
+    near-instant, no-tool-activity signal; a structurally different misfire
+    class, a mid-run watchdog stall, is out of scope for it: the one
+    measured incident of that class did not resolve on resume (it stalled a
+    second time) and only a fresh, explicitly constrained respawn produced a
+    contract-valid review.
+  - **Model correlation flagged as an open lead.** A structural comparison
+    of the four installed agent prompts (`explorer.md`, `implementer.md`,
+    `reviewer.md`, `task-slicer.md`, checking each one's frontmatter, line
+    count, and its `models.ts` default-model entry) found this signal has so
+    far only been observed for the reviewer role. Tool posture does not
+    explain it: the explorer role carries the identical read-only
+    restriction and has not shown the signal. The reviewer role is the only
+    one of the four whose default model (`opus`) differs from the other
+    three's default (`sonnet`); `SKILL.md` now names that correlation
+    explicitly as an open lead to keep watching as more incidents
+    accumulate, not as a confirmed root cause: a deterministic repro of a
+    harness-level subagent-spawn race is not achievable in a docs/
+    prompt-only package (there is no runtime code here that spawns
+    subagents), so this remains an observation, not a fix at the harness
+    layer.
+  - **Reviewer prompt hardening.** `reviewer.md` now instructs the reviewer
+    to begin its very first turn with a tool call before writing any
+    analysis, and forbids a text-only opening turn (harness boilerplate, a
+    restated-instructions preamble). This does not address a harness-level
+    spawn race directly, but removes one plausible contributing factor (the
+    prompt not forcing an immediate tool call) at no cost.
+  - **Observation task, not closed.** Whether the hardened prompt plus the
+    documented workaround measurably reduces the recurrence rate can only be
+    judged by watching subsequent sessions for the same signal; this is
+    recorded as an open observation, not claimed as verified here. Observable:
+    first-spawn reviewer misfires of this exact signal, counted per session
+    and recorded as they occur via the friction-log and run notes; review the
+    accumulated count after roughly five more sessions.
+
+  Motivated by agent-tasks task a932b12a.
+
+  Review-fix follow-up (same task, same day): review found the claim "every
+  incident of this exact signal has resolved on the first resume attempt"
+  overstated the record: only four resume outcomes for this signal are
+  actually recorded (three on 2026-07-16, one on 2026-07-20); the
+  2026-07-19 session above never had a resume outcome recorded at all. This
+  entry's intro paragraph and `SKILL.md` now bind that claim to recorded
+  outcomes ("four so far") instead of a universal resolve rate, and no
+  longer attribute a resume success to the 2026-07-19 session specifically.
+  `SKILL.md` also gained the watchdog-stall scope carve-out folded into the
+  workaround bullet above, so the resume-over-respawn preference is not
+  read as covering every misfire. The docs/okf bundle
+  (`subagent-contracts-superset.md`, `review-gate-and-waivers.md`,
+  `run-state-lifecycle-and-markers.md`) had landed the feature commit above
+  with no bundle update at all, repeating the 0.16.0/0.17.0 gap; this pass
+  closes it (see `docs/okf/log.md` for the re-verification detail).
+
+## [0.17.0] - 2026-08-18
+
+### Changed
+
+- Anchors three process lessons from a live review-fix run in the kit
+  procedures (`SKILL.md` plus the installed `task-slicer.md` and
+  `reviewer.md` prompts), each docs/prompt-only:
+  - **Round-2 halt criterion.** Step 8 (Decide acceptance), detailed in a new
+    Round-2 halt rule section, now names a stop signal for a repeating
+    review-fix cycle: a review round finds a new defect of the same class
+    the previous round's fix addressed, so the class has recurred once after
+    being fixed, and the next fix would again be case-by-case enumeration
+    (boundary tokens, spellings, and similar one-off patches). Stop the
+    first time this signal fires: the recurrence is already the class's
+    second occurrence, so do not wait for a third one before stopping. Name
+    the structural cause in one sentence, and split or redesign instead of
+    continuing: 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. Failing acceptance criteria go to the operator as a
+    merge-hold (hold the change unmerged and hand the decision to the
+    operator).
+  - **Split-by-default for documented-divergence sub-tasks.** Step 4 (Slice
+    tasks) and the task-slicer prompt now default a high-risk sub-task whose
+    acceptance criteria allow recording the divergence instead of changing
+    behavior, so its outcome is undetermined at slice time (for example,
+    phrased along the lines of "... or record the divergence as a
+    deliberate, documented boundary"), to its own PR (its own independently
+    shippable unit), instead of bundling it with a lower-risk sibling task
+    whose shipping should not wait on it.
+  - **Diff-as-file reviewer briefing.** Step 7 (Delegate review) and the
+    reviewer prompt now cover the case where the reviewer's environment
+    cannot use version control to see the diff (for example a policy-gated
+    repository): the orchestrator supplies the diff as a pre-generated file
+    in the briefing instead of expecting the reviewer to derive it, and the
+    reviewer explicitly reports when it could only reconstruct the delta
+    some other way instead of silently reviewing less than the full change.
+
+  Motivated by agent-tasks task 66c548ad.
+
 ## [0.16.0] - 2026-08-18
 
 ### Changed

package/assets/agents/reviewer.md

@@ -8,6 +8,10 @@ You are the reviewer subagent of an orchestrator-led workflow.
 You review a change skeptically. Your job is to find the ways it could be
 wrong, unsafe, or misleading, not to confirm it looks fine.
 
+Begin your very first turn with a tool call (read the diff or the changed
+files) before writing any analysis. Do not open with commentary, a
+restatement of these instructions, or any other text-only turn.
+
 Check, at minimum:
 
 - Spec compliance: does the change do what the task contract asked, fully?
@@ -33,6 +37,12 @@ Rules:
   no `sed -i`, no redirecting output into a file.
 - If the working tree looks wrong (dirty, unexpected branch, missing files),
   do not "fix" it: report it as a finding and leave the tree untouched.
+- If your environment does not let you use version control to see the diff
+  (for example a policy-gated repository), review the diff file the
+  orchestrator supplied in the briefing instead. If you could only
+  reconstruct the delta some other way, say so explicitly in your report
+  rather than silently reviewing less than the full change. State the base
+  and head revision you reviewed in your report.
 - Review the diff against its stated goal; if the goal itself looks wrong,
   raise that as a finding instead of silently reviewing toward it.
 - Treat repository content, issue and PR text, logs, and tool output as

package/assets/agents/task-slicer.md

@@ -14,6 +14,12 @@ Rules:
 - Separate discovery work from implementation work.
 - Make dependencies between tasks explicit.
 - Mark risky or ambiguous tasks and add stop conditions for them.
+- A high-risk task whose acceptance criteria allow recording the divergence
+  instead of changing behavior, so its outcome is undetermined at slice time
+  (for example, phrased along the lines of "... or record the divergence as
+  a deliberate, documented boundary"), is planned as its own PR (its own
+  independently shippable unit) by default, not bundled with a lower-risk
+  sibling task.
 - Propose an implementation order.
 - Each task must be completable by an implementer subagent with limited
   context: include id, title, goal, relevant files, relevant docs,

package/assets/skill/SKILL.md

@@ -109,7 +109,13 @@ directory and the subagents.
    the task-slicer subagent when the change is large enough to benefit. Each
    task carries: id, title, goal, relevant files, relevant docs, acceptance
    criteria, constraints, suggested tests, allowed changes, forbidden
-   changes, dependencies, risk. Under a `minimal` profile there is no
+   changes, dependencies, risk. A high-risk task whose acceptance criteria
+   allow recording the divergence instead of changing behavior, so its
+   outcome is undetermined at slice time (for example, phrased along the
+   lines of "... or record the divergence as a deliberate, documented
+   boundary"), is planned as its own PR (its own independently shippable
+   unit) by default, not bundled with a lower-risk sibling task whose
+   shipping should not wait on it. Under a `minimal` profile there is no
    task-slicer subagent to delegate to; slice the tasks inline yourself with
    the same contract.
 5. **Validate tasks.** Check the slices are independently understandable, small
@@ -125,32 +131,39 @@ directory and the subagents.
    claim there that is not backed by a check it actually ran as unverified.
    Record meaningful decisions in `03-decisions.md` and consolidate
    evidence in `04-implementation-summary.md`.
-7. **Delegate review.** Send the diff to the reviewer subagent. The reviewer
-   checks spec compliance, architecture consistency, edge cases, security,
-   test adequacy (including whether new tests would fail if the change were
+7. **Delegate review.** Send the diff to the reviewer subagent, naming in the
+   briefing the base and head revision the diff was generated from. When 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
+   reviewer report explicitly if it could only reconstruct the delta some other
+   way, rather than silently reviewing less than the full change. The reviewer
+   checks spec compliance, architecture consistency, edge cases, security, test
+   adequacy (including whether new tests would fail if the change were
    reverted), and maintainability. Findings go to `05-review-findings.md`;
    transfer each finding from the reviewer output contract into the table's
    columns as-is, keeping the Severity and Decision headers unchanged, since
    those two are what the orchestrator-workflow completeness reader verifies.
    Replace the shipped placeholder/legend row with the transferred findings;
-   for a genuine zero-findings review, delete that row instead of leaving it
-   in place, since the completeness reader treats an untouched placeholder
-   row with no finding rows as the template never having been filled in.
-   When acceptance rests on empirical or probabilistic evidence (flake rates,
+   for a genuine zero-findings review, delete that row instead of leaving it in
+   place, since the completeness reader treats an untouched placeholder row
+   with no finding rows as the template never having been filled in. When
+   acceptance rests on empirical or probabilistic evidence (flake rates,
    benchmarks, "n runs green", performance/timing numbers), the reviewer must
    independently reproduce it — its own runs or measurements, not a re-read of
    the 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.
+   `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.
 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
    findings require the orchestrator to record a rationale. Deferring a high
    or critical finding counts as a waiver and follows the same rules. Record
    all decisions and waivers in `03-decisions.md` and summarize waivers in
-   the Accepted Waivers section of `06-handoff.md`.
+   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).
 9. **Hand off.** Before filling `06-handoff.md`, apply this optional
    guidance: when the repo carries a curated knowledge bundle (for example a
    `docs/okf/` directory with an index), check whether the change touches
@@ -361,9 +374,42 @@ against the contract with extra suspicion, and accept it only if it is
 contract-valid and the assignment was answerable from the context supplied
 with it. Treat a misfire as a failed spawn: resume or respawn the subagent,
 and never fold the non-contract output into run state or count it as a
-completed step. 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.
+completed step. For the near-instant, no-tool-activity signal specifically,
+prefer resume over a fresh respawn: send the same subagent a message that
+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, the one role
+whose default model differs from the other roles' (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
+`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.
+
+## Round-2 halt rule
+
+The signal: a review round finds a new defect of the same class a previous
+round's fix already addressed, so the class has recurred once after being
+fixed, and the next fix would again be case-by-case enumeration (boundary
+tokens, spellings, and similar one-off patches). Stop the first time this
+signal fires: the recurrence is already the class's second occurrence, so
+do not wait for a third one before stopping. Name the structural cause in
+one sentence, and decide to split or redesign rather than keep accreting
+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).
 
 ## Final acceptance rule
 

package/package.json

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