Orchestrator: optional spec/plan gate — a reviewable plan artifact before implementation starts

[robercano]

Context (from the orchestrator landscape comparison)

Today the orchestrator scopes an issue in-conversation and goes straight to implementation; the first human-vetoable artifact is the finished PR. If the scoping was wrong (misread intent, wrong module, over-engineered approach), you discover it after the full implement→gate→review token spend, and your only lever is CHANGES_REQUESTED on completed work.

Looper's pipeline is built around the opposite bet, and it's their best design idea: the planner's output is a spec PR (looper:spec-reviewing) that goes through review and must reach looper:spec-ready before the worker touches code — and the worker then implements on the same PR, so plan and implementation share one audit trail. "You can pause, intervene, or take over at any boundary" (Looper README). Gas Town encodes the same idea as step-gated "molecule" workflows (examine → design → assess → implement → validate) where each step must complete before the next unlocks.

For reCode this also compounds with #94 (injection hardening): a plan gate means untrusted issue text can at worst produce a visible bad plan, not silent bad code.

Proposal

Make it opt-in per issue (cheap issues shouldn't pay the overhead):

1. New adapter knob plan.gate: off (default, today's behavior) | label | always. With label, adding a plan-first label to an issue makes the loop's ADVANCE spawn only the scoping phase.
2. The orchestrator posts the plan as a structured issue comment (scope, module, files expected to change, approach, acceptance mapping) and labels the issue plan-review + needs-human (uses Loop/cockpit: needs-human signal — label + push notification when the loop blocks on the owner #99's signal). No code yet.
3. Owner approves by replacing the label with plan-approved (or comments requested changes → orchestrator revises the plan comment, bounded attempts). Next tick's ADVANCE sees plan-approved and proceeds to normal implementation, with the approved plan text injected into the implementer prompt as the authoritative scope.
4. Reviewer agents receive the approved plan too, so "diff exceeds approved scope" becomes a checkable reject reason — a free tightening of the correctness lens.

Why a comment and not a spec PR like Looper: a PR-per-plan doubles PR traffic and worktree churn for marginal benefit at our scale; the comment keeps one artifact per issue and zero extra branches. (Decision point below if you prefer the PR form.)

Acceptance criteria

• plan-first-labeled issue: loop produces a plan comment and stops; nothing is implemented until plan-approved.
• Approved plan text reaches both implementer and reviewers; scope-exceeding diffs get rejected with that reason.
• Default off keeps current single-pass behavior byte-identical; smoke tests cover both paths.
• USAGE.md documents the label workflow next to backlog/planned.

Decision points for you

• Plan-as-comment (recommended) vs plan-as-spec-PR (Looper-style, better diff/review ergonomics, more churn)?
• Should always mode exist at all, or is per-label opt-in enough?
• Who may approve a plan — owner only (consistent with planned policy)?

🤖 Generated with Claude Code

https://claude.ai/code/session_014Gu82LWNkdzhrDFSQ7EZmB