# Orchestrator Retry And Escalation Policy

Use this policy when QA returns `BLOCKED` during an Orchestrator-controlled Developer -> QA loop.

The goal is to allow narrow, safe fixes while preventing hidden scope expansion, ambiguous product decisions, or endless retries.

## Retry And Escalation States

| State | Meaning | Next Owner |
| --- | --- | --- |
| `qa_blocked_fixable` | QA found a concrete, retry-safe implementation, docs, test, validation, or cleanup defect. | Developer |
| `qa_blocked_requires_decision` | QA found ambiguity, conflicting evidence, unclear requirements, prose-only uncertainty, or a decision the agent should not invent. | Human or Requirements role |
| `qa_blocked_scope_change` | Fixing the blocker would require changing scope, acceptance criteria, requirements, dependencies, app behavior outside scope, or package dependencies. | Human or Orchestrator |
| `retry_limit_reached` | The chunk reached the retry limit and should not continue automatically. | Human |
| `manual_intervention_required` | State is ambiguous, unsafe, unclassified, or requires unavailable services/permissions. | Human |

`qa_blocked_fixable` is the only QA BLOCKED state that should produce a Developer `dev-fix` prompt automatically.

## QA Blocker Classification

QA must classify every BLOCKED review with one of:

- `fixable`: a focused Developer retry is safe.
- `requires_decision`: product, requirements, runtime, validation, or evidence ambiguity needs human/requirements input.
- `scope_change`: requested fix expands or changes scope.
- `retry_limit_reached`: maximum retries reached.

QA should also label evidence behind each blocker:

- `machine-verified failure`
- `simulation-verified failure`
- `runtime-verified failure`
- `manual-review concern`
- `prose-only uncertainty`
- `requirements ambiguity`
- `scope-change request`

## Orchestrator Decision Rules After QA BLOCKED

1. Read `## QA Review`, latest `### QA Pass N`, and `ai/commands/workflow-state.sh`.
2. Confirm the QA review includes blocker classification and evidence type.
3. Count Developer passes in `## Pass History`.
4. If Developer pass count is at or above the retry limit, stop with `retry_limit_reached`.
5. If classification is `fixable`, send a focused Developer fix prompt with `ai/commands/prompt-synthesize.sh dev-fix`.
6. If classification is `requires_decision`, stop and request human or requirements clarification.
7. If classification is `scope_change`, stop and request human approval or a new chunk.
8. If classification is missing, contradictory, or unsupported by evidence, stop with `manual_intervention_required`.

## Retry Limits

- Maximum Developer attempts per chunk: 3 total.
- That means the initial Developer pass plus up to 2 focused fix passes.
- Validation reruns without file changes do not count as a retry.
- A new Developer pass is required for every focused fix attempt.
- Do not continue automatically after `### Developer Pass 3` receives a QA BLOCKED verdict.

## Focused Fix Rules

A focused retry may only address QA blockers that are:

- within current scope.
- supported by machine, simulation, runtime, or concrete manual-review evidence.
- fixable without changing requirements.
- fixable without changing package dependencies unless the chunk already allows it.
- fixable without inventing product decisions.

The Developer fix prompt must not include unrelated cleanup, refactors, or new features.

## Stop Conditions

Stop and request human intervention when:

- QA blocker classification is missing.
- QA blocker evidence is prose-only and material to correctness.
- requirements are ambiguous or conflict with implementation.
- fix requires scope or acceptance criteria changes.
- fix requires unavailable credentials, services, production data, or unsafe runtime access.
- Developer and QA disagree about correctness.
- retry limit is reached.
- generated prompts or helper state disagree with chunk notes.

## Handoff Requirements

Use `ai/standards/workflow-handoff.md` for handoff field meanings and command
categories. Retry policy owns blocker classification; workflow handoff owns how
those decisions are expressed in handoff fields.

- `qa_blocked_fixable` should hand off to focused Developer fix prompt
  synthesis.
- escalation states should hand off to human review with the decision needed
  stated clearly.

## Completion Boundary

Retry policy never authorizes completion or commit. After QA PASS, Orchestrator must still run:

```sh
ai/commands/workflow-state.sh --ready-to-complete
ai/commands/workflow-summary.sh
```

Then stop for human review when requested by the chunk or user.