multi-agent orchestration: Multi-Agent Roles: Planner, Implementer, Critic

# agents/contracts.py
from pydantic import BaseModel, Field
from typing import Literal

class PlanStep(BaseModel):
    id: str
    intent: str
    files: list[str] = Field(default_factory=list)
    acceptance: str

class PlanArtifact(BaseModel):
    goal: str
    steps: list[PlanStep]
    budget_tokens: int = 50_000

class CriticVerdict(BaseModel):
    decision: Literal["ACCEPT", "REJECT"]
    step_id: str
    evidence: list[str]
    required_fix: str | None = None

// runtime/roleGate.ts
export function assertTool(role: "planner" | "implementer" | "critic", tool: string) {
  const allow: Record<string, Set<string>> = {
    planner: new Set(["search", "list_files", "write_plan"]),
    implementer: new Set(["apply_intent", "run_tests", "read_file"]),
    critic: new Set(["read_file", "read_diff", "write_verdict"]),
  };
  if (!allow[role].has(tool)) throw new Error(`tool_denied:${role}:${tool}`);
}

# ✅ Explicit artifact pipeline
python agents/planner.py  --ticket T-441 --out /artifacts/plan.json
python agents/implementer.py --plan /artifacts/plan.json --out /artifacts/diff.json
python agents/critic.py --plan /artifacts/plan.json --diff /artifacts/diff.json --out /artifacts/verdict.json

MAX_CRITIC_ROUNDS = 3

def next_action(verdict: CriticVerdict, round_i: int) -> str:
    if verdict.decision == "ACCEPT":
        return "merge_gate"
    if round_i >= MAX_CRITIC_ROUNDS:
        return "human_queue"  # ✅ escalate, don't ping-pong
    return "replan_or_fix"