Reviewer Rejection Protocol

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Try this to request a code review:

Review the changes in src/auth/ and check for security issues

Try this to trigger peer review:

Lead, review the PR from Fenster

When a reviewer (Lead, Tester) rejects work, the original agent is locked out from self-revision. This prevents endless fix-retry loops and forces human oversight or reassignment.

How It Works

1. Agent submits work — Creates draft PR, requests review from Lead or Tester.
2. Reviewer evaluates — Checks code quality, test coverage, adherence to directives.
3. Reviewer decision:
   • Approve → PR merges, issue closes, agent unlocked.
   • Request changes → Agent is locked out, work routes to another agent or escalates.

Strict Lockout

Once a reviewer rejects work, the original agent cannot revise their own submission. This is a hard constraint:

• Agent A writes code → Lead rejects
• Agent A cannot fix and resubmit
• Coordinator must reassign to Agent B or escalate to user

Why Lockout?

Without lockout:

• Agent A writes buggy code
• Lead rejects: “This has race conditions”
• Agent A fixes, resubmits
• Lead rejects again: “Still broken”
• Agent A fixes, resubmits
• Infinite loop, no progress

With lockout:

• Agent A writes buggy code
• Lead rejects: “This has race conditions”
• Agent A locked out
• Coordinator assigns Agent B (fresh perspective) or escalates to user
• Work gets done or human intervenes

Reassign vs. Escalate

When rejection happens, coordinator has two options:

Reassign Example

1. Fenster (Frontend) writes a React component → Lead rejects: “Accessibility issues”
2. Fenster locked out
3. Coordinator checks skills: Hockney (Frontend) has accessibility expertise
4. Work reassigned to Hockney
5. Hockney fixes and resubmits

Escalate Example

1. Backend writes API logic → Tester rejects: “Integration tests fail”
2. Backend locked out
3. Coordinator reassigns to Core Dev → Core Dev also fails review
4. Core Dev locked out
5. All agents exhausted → Coordinator escalates to user: “Issue #42 rejected twice. Need guidance or manual fix.”

Lockout Scope and Duration

An agent locked out of issue #42 can still work on issue #43, #44, etc. Lockout is not a global ban.

Deadlock Handling

If all capable agents are locked out:

1. Coordinator detects deadlock: no available agents for work.
2. Coordinator escalates to user: “All agents locked out for issue #42. Options: 1) Manual fix, 2) Unlock an agent and provide guidance, 3) Close as won’t-fix.”
3. User chooses resolution.

This prevents the team from getting stuck in a state where no one can proceed.

Reviewer Authority

Only designated reviewers can lock out agents:

Other agents (Frontend, Backend, DevRel) cannot lock out peers.

Unlocking an Agent

“Unlock Fenster for issue #42”

Coordinator clears the lockout. Fenster can now revise the PR. Use this when:

• Reviewer feedback was unclear, you’ve provided better guidance
• Agent legitimately misunderstood requirements
• External factors (API change, dependency update) invalidated the original rejection

Lockout Logs

Lockouts are recorded in .squad/orchestration-log/:

[2024-01-15 15:45:30] REVIEW: Lead rejected PR #12 (author: Fenster)
[2024-01-15 15:45:31] LOCKOUT: Fenster locked out for issue #42
[2024-01-15 15:45:35] REASSIGN: Issue #42 → Hockney (accessibility expertise)
[2024-01-15 16:20:10] REVIEW: Lead approved PR #13 (author: Hockney)
[2024-01-15 16:20:11] UNLOCK: Fenster unlocked (issue #42 resolved)

Trust Levels for PR Management

This section covers the spectrum of human oversight for Squad-created PRs:

1. Full Review (Default)

Every PR requires human approval before merge. This is the default and recommended for team repos, shared codebases, and anything with external collaborators.

When to use: Team repositories, public packages, shared codebases where multiple people depend on stability.

Risk: Low — human gate on every change.

2. Selective Review

Squad creates and reviews PRs, but the human only reviews PRs that touch specific paths or domains they care about. Everything else merges after agent review.

When to use: Personal projects with established patterns where you trust Squad’s judgment on routine changes (dependency updates, test fixes, doc improvements).

Risk: Medium — some changes skip human eyes.

3. Self-Managing (Personal Repos Only)

Squad creates, reviews, approves, and merges its own PRs. The human only jumps in when an issue is explicitly flagged for review.

When to use: Solo personal projects where you’re the sole maintainer and experimentation speed matters more than pre-merge safety.

Risk: Higher — but fast; review PRs retroactively.

Decision Matrix

Important: Self-managing mode doesn’t mean unmonitored. Use Ralph’s work monitoring, Teams notifications, and periodic code review to stay informed. The difference is that you review after merge rather than before.

Sample Prompts

Lead, review PR #15

Triggers review. Lead evaluates code and either approves (merge + unlock) or rejects (lockout original author).

Why is Fenster locked out?

Coordinator explains: “Fenster was locked out for issue #42 after Lead rejected PR #15 due to security concerns.”

Unlock Fenster for issue #42 — I've given him better guidance

Clears lockout. Fenster can now revise the PR with your additional context.

Reassign issue #42 from Fenster to Hockney

Manual reassignment. Fenster remains locked out, Hockney takes over the work.

Escalate issue #42 to me — the team is stuck

Coordinator notifies you of deadlock or repeated rejections. You provide manual intervention or guidance.