docs(orchestrate): batch review fixes and clarify actor routing

[thomasluizon]

Fixes thomasluizon/orbit-tickets#537.

What changed

• Both canonical launcher signatures include --tier <default|mechanical> and --relaunch-reason <text>.
• One accepted Pullfrog review produces one deduplicated finding set and at most one fix commit.
• A batch without a commit spends no caps.reviewFixAttempts budget.
• The orchestrator handles narrow review fixes directly. Larger batches produce one worker order.
• After a worker pushes, the orchestrator resolves every identified thread and requests a fresh review.
• --re-review can accept any current-head review submitted after its request.
• A registered exact-head pullfrog-approval SUCCESS is the verdict.
• When that check is absent, reviewState APPROVED with reviewedCommit equal to the head stands in for it.
• COMMENTED and empty-body reviews are progress markers, not verdicts.
• thomasluizon/orbit-tickets#542 tracks the stop-after-commit contract that will remove this review race.
• Body-only FILE and not-applicable findings request a fresh same-head review after recording their disposition.

External interface evidence

This run confirmed the launcher flags with git show 94701d569cd6d7a0a2ff04a41264acc12f6aa346:tools/launch-worker.mjs. The source declares --tier <default|mechanical> and --relaunch-reason <text>, so the documentation matches the source.

This run also read tools/list-bot-threads.mjs. Its --re-review path accepts any completed current-head review submitted after the request, including COMMENTED.

This run read tools/lib/readiness-receipt.mjs, tools/verify-delivery.mjs, and tools/record-readiness.mjs. They accept a registered green check, or an exact-head APPROVED review only when that check is absent.

Contract timing

This contract change takes effect for the next run. The run producing it kept executing the contract it read at entry.

Test evidence

• node tools/test-tools.mjs: ORBIT TOOLS GATE OK.
• node .claude/hooks/test-hooks.mjs: ORBIT HOOKS OK.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
orbit-ui-mobile-web	Ignored		Sep 15, 2026 7:22am UTC

[pullfrog]

ℹ️ One documentation reference needs correction.

Reviewed changes I reviewed the ownership and salvage-policy changes in the current one-commit patch.

• Salvage scope — Limits the existing no-implementation prohibition to dead-worker salvage and points Pullfrog fixes to step 8.
• Review-fix actor — Allows the orchestrator to implement bounded review fixes while leaving ticket-sized work with workers.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The new batch contract has unresolved execution contradictions that can route a review fix to the wrong actor or leave a same-head review stuck.

Reviewed changes I reviewed the second commit added since the prior Pullfrog review.

• Worker-budget routing - Added explicit default and mechanical tier selection plus recorded reasons for launches beyond the branch cap.
• Batched review findings - Combined thread and body findings into one deduplicated batch with one commit and one attempt per accepted review.
• Contract clarification - Corrected the actor-rule citation and scoped self-edit restrictions to the current run and D95.

⚠️ The contract can activate before its launcher

PR #964 remains open and is independently based on redesign/main. If this PR merges first, the next orchestrate run reads instructions for flags and a branch cap that the base launcher and configuration do not yet implement.

Technical details

# Sequence the launcher implementation before its operating contract

## Affected sites
- `.claude/skills/orchestrate/SKILL.md:658-668` - Requires `--tier`, `--relaunch-reason`, and `caps.workerLaunchesPerBranch`.
- `tools/launch-worker.mjs:65-70,119-123` on the current base - Parses neither new flag and always resolves `default`.
- `.claude/orchestrator.json:12-18,30-35` on the current base - Declares neither the `mechanical` tier nor the branch launch cap.
- [PR #964](https://github.com/thomasluizon/orbit-ui-mobile/pull/964) - Carries the required implementation but is not merged or included in this branch.

## Required outcome
- Ensure PR #964 lands before this contract can reach `redesign/main`, or stack this branch on the implementation so the documented interface and implementation become available atomically.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The new attempt-accounting wording can exhaust caps.reviewFixAttempts inconsistently for batches that intentionally create no commit.

Reviewed changes I reviewed the third commit added since the prior Pullfrog review.

• Actor routing — Assigned ordinary review fixes to the orchestrator and reserved worker dispatch for batches containing ticket-sized FIX findings.
• Same-head dispositions — Added a PR comment and fresh APPROVED re-review path for body-only FILE and not-applicable findings.
• Launcher contract — Added tier and relaunch flags to both canonical launcher signatures.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

ℹ️ No critical issues in the merge-forward; the PR evidence needs one refresh.

Reviewed changes I reviewed the merge of redesign/main since the prior Pullfrog review.

• Merged launcher support — Brought the merged PR #964 implementation of worker tiers, relaunch reasons, and the per-branch launch cap onto this branch.
• Preserved the skill patch — Left the one-file net patch unchanged while making its launcher contract available on both the base and head.

ℹ️ The test evidence describes the pre-merge state

The PR body still says commit 94701d56 is absent from redesign/main and that the branch launcher lacks both new flags. Merge commit 969a19ec brought that implementation onto the branch and advanced the base to it, so the durable test narrative is now inaccurate.

Technical details

# Refresh the PR evidence after the launcher merge

## Affected sites
- PR body, `## Test evidence` — Still records the five signature failures and says the dependency is absent from the base.
- `tools/launch-worker.mjs:38-41,73-83,288-299` — Now implements `--tier`, `--relaunch-reason`, and branch-cap enforcement.
- `.claude/orchestrator.json:12-20,34-39` — Now declares the mechanical tier and `caps.workerLaunchesPerBranch`.

## Required outcome
- Make the PR body's test evidence describe the current head and stop claiming that the merged launcher implementation is absent.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[thomasluizon]

@pullfrog review

[pullfrog]

Important

The large review-fix path can run the mandatory push before its threads are resolved, allowing Pullfrog to review an unresolved thread state. Earlier attempt-accounting and PR-evidence feedback also remains open.

Reviewed changes I reviewed the full four-commit patch against redesign/main, including the merged launcher support and the existing worker delivery contract.

• Launcher routing: Documents default and mechanical tiers plus recorded reasons for launches beyond the per-branch cap.
• Review batching: Combines thread and body findings into one classified set with at most one worker order and one fix commit.
• Fix ownership: Assigns narrow review fixes to the orchestrator, sends ticket-sized batches to a worker, and confines the no-edit prohibition to salvage.
• Same-head adjudication: Records FILE and not-applicable dispositions before requesting a fresh same-head review.
• Contract timing: Makes skill and harness changes effective for the next run without weakening D95.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The post-push re-review still cannot guarantee that the resolved-thread state supplies the final verdict.

Reviewed changes I reviewed the new ordering clarification and evidence updates added since the prior Pullfrog review.

• Attempt accounting — Clarified that only the batch's single commit consumes caps.reviewFixAttempts, while no-commit disposition batches spend nothing.
• Worker review ordering — Documented the current worker push-before-resolution behavior and added an explicit post-resolution --re-review step.
• PR evidence — Replaced the stale launcher test narrative with current passing harness results and source evidence.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

Important

The replacement verdict rule disagrees with the executable readiness contract, so compliant runs can enforce different completion conditions.

Reviewed changes I reviewed the verdict clarification added since the prior Pullfrog review.

• Verdict routing — Recast reviews accepted by --re-review as progress and introduced a separate exact-head verdict requirement.
• Review-state classification — Clarified that COMMENTED and empty-body reviews are progress markers rather than verdicts.
• Ticket traceability — Qualified the stop-after-commit follow-up as thomasluizon/orbit-tickets#542.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes I reviewed the verdict fallback correction added since the prior Pullfrog review.

• Verdict fallback — Replaced the check-and-review conjunction with the executable contract: a registered successful pullfrog-approval is sufficient, while an exact-head approval stands in only when that context is absent.
• Canonical review fields — Named the reviewState and reviewedCommit output fields used by list-bot-threads.mjs while preserving COMMENTED and empty-body reviews as progress markers.

  ^{｜ View workflow run ｜ Using GPT Sol ｜ 𝕏}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud