# Orchestration Workflow

Use this standard when an Orchestrator manages a chunk through Developer implementation and QA review.

Canonical workflow states are defined in `ai/standards/workflow-state.md`. Use those state names when deciding whether the next step is requirements intake, requirements review, chunk planning, Developer implementation, QA review, completion, commit, or manual intervention.

Workflow handoffs are defined in `ai/standards/workflow-handoff.md`. Every Orchestrator-controlled transition should use that standard for required fields, field meanings, and command categories.

Retry and escalation decisions are defined in `ai/standards/orchestrator-retry-policy.md`. Use that policy whenever QA returns `BLOCKED`.

For approved work packages, use `ai/standards/chunk-autopilot.md` as the default
parent loop and canonical full-show lifecycle. This standard still defines the
per-chunk Developer -> QA mechanics inside Chunk Autopilot.

## Ownership

- Orchestrator owns chunk readiness, iteration decisions, completion decisions, and manual escalation.
- Developer implements only the assigned chunk, updates tests/docs when required, runs requested validation, and reports status. Developer does not self-approve DONE.
- QA reviews against `ai/standards/done.md`, `ai/standards/qa-gates.md`, the chunk scope, and applicable conventions. QA returns `PASS` or `BLOCKED`.

## Operator Context Messages

Operator prompts, assistant inline answers, and assistant work updates that are
operationally useful should be recorded through the Runtime message stream when
the runner has a repository-controlled producer boundary:

```sh
node ai/runtime/dist/cli.js runtime message-record \
  --type operator_prompt|assistant_inline_answer|assistant_work_update \
  --text "<message>"
```

The message stream is context only. It must not mutate workflow authority,
approval state, dispatcher state, lifecycle state, service truth, or Runtime
Health truth.

The canonical consumer path is the Admin Runtime Health GraphQL projection and
the Health-page `Operator / Assistant Messages` window. Browser freshness must
come from Runtime State Journal invalidation followed by GraphQL refetch. Socket
payloads may announce invalidation only; they must not become message or service
truth.

Message producers must preserve redaction, source/type metadata, bounded
retention, and correlation metadata where available. If a runner cannot call the
producer directly, record the limitation in carry-forward debt instead of
relying on chat memory or markdown prompt text as a deterministic source.

## Default Loop

1. Confirm the chunk goal, scope, out-of-scope items, acceptance criteria, dependencies, and validation.
2. Send a focused implementation prompt to Developer.
3. Developer implements, validates, updates Execution Notes, and reports `git status` plus `git diff --stat`.
   Developer also appends or updates the current `### Developer Pass N` entry in `## Pass History`.
4. Send the implemented chunk to QA.
5. QA reviews, runs required validation, decides runtime smoke applicability, verifies cleanup, and returns `PASS` or `BLOCKED`.
   QA also updates `## QA Review` as the current verdict summary and appends or updates the current `### QA Pass N` entry in `## Pass History`.
6. If QA returns `PASS`, Orchestrator may complete/archive the chunk after required notes and status are present. Under approved Chunk Autopilot, Orchestrator also safely stages and commits the chunk, then continues to the next approved queue item unless a stop condition applies.
7. If QA returns `BLOCKED`, Orchestrator classifies the blocker using `ai/standards/orchestrator-retry-policy.md`.
   Send Developer a focused fix prompt only when the state is `qa_blocked_fixable`.
8. Repeat Developer -> QA until one stop condition is reached.

## Iteration Limit

The default maximum is 3 Developer implementation attempts for a chunk, including the initial implementation and up to 2 focused fix attempts.

Count attempts from `### Developer Pass N` entries in `## Pass History`. If pass history is missing, infer conservatively from the current chunk notes and add pass history before continuing.

Do not silently continue beyond the limit. Ask for manual intervention instead.

## Manual Intervention Conditions

Request human review before continuing when:

- Requirements are ambiguous.
- QA and Developer disagree about correctness or scope.
- Runtime smoke cannot be executed.
- Validation requires unavailable services.
- The needed fix would change the approved scope.
- The maximum iteration count is reached.
- QA BLOCKED lacks blocker classification or evidence type.
- QA BLOCKED is classified as `requires_decision`, `scope_change`, or `retry_limit_reached`.
- The chunk appears to depend on missing requirements, data, credentials, or infrastructure.

## Focused Fix Prompts

When QA reports `BLOCKED`, the Orchestrator fix prompt should include:

- The active chunk path.
- The QA verdict and blocking issues.
- The exact goal for the fix cycle.
- In-scope fixes only.
- Explicit out-of-scope protections.
- Required validation commands.
- Required reporting: Execution Notes, `git status`, and `git diff --stat`.

Generate this prompt only for `qa_blocked_fixable`. If the blocker needs a decision, changes scope, lacks evidence, or reaches the retry limit, request human intervention instead.

Avoid adding new features or unrelated cleanup to fix prompts.

## Completion Decision

Complete a chunk only when:

- QA returns `PASS`, or a human explicitly approves completion.
- Required validation and runtime smoke decisions are documented.
- Test/dev artifacts are cleaned up or accepted as documented.
- Execution Notes are current.
- `## QA Review` reflects the current QA verdict.
- `## Pass History` includes the latest Developer and QA passes needed to explain the current state and iteration count.
- `git status` and `git diff --stat` have been reported.

Before archiving, run:

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

If the command reports blockers, do not complete the chunk. Send a focused Developer fix prompt, run QA, or request manual intervention according to the reported state.

Use `ai/tools/operator-daemon/request-action.sh --action complete_chunk --target <path-to-active-chunk>`
when archiving an active chunk after approval. Raw `complete-chunk.sh` and
`workflow-approve-action.sh --action complete-chunk` are legacy/manual
fallbacks behind the daemon action.

For registered local/dev actions, use the trusted operator daemon instead of
Codex platform/tool escalation:

```sh
ai/tools/operator-daemon/request-action.sh --action git_add_approved --files "<reviewed files>"
ai/tools/operator-daemon/request-action.sh --action git_commit --message "<message>"
ai/tools/operator-daemon/wait-result.sh <request-id>
```

Do not run daemon `run-once.sh` directly as a shortcut. The trusted daemon loop
must process registered actions; direct diagnostic use requires explicit
operator approval through the operator question path.

Before requesting Codex platform/tool escalation for an unregistered action,
run `ai/commands/platform-escalation-preflight.sh` or
`workflow-approve-action.sh --action platform-tool` for the exact unregistered
command/action.
Only request the platform prompt after approval; denied platform-tool approvals
stop the escalation.

## Workflow State Sources

Canonical state is the orchestration truth. Markdown sections remain the human-readable audit trail.

Use these chunk sections as the source of truth:

- `## Execution Notes`: current Developer implementation summary.
- `## QA Review`: current QA verdict summary.
- `## Pass History`: chronological Developer/QA pass audit trail.

When these disagree, treat `## QA Review` as the current verdict, use the latest `## Pass History` entry to explain the latest action, and request manual intervention if the next action is ambiguous.

Use `ai/commands/workflow-state.sh` as the shared read-only state check for active chunk count, latest pass, QA verdict, stale QA risk, iteration count, recommended next action, and completion readiness.

If `workflow-state.sh` reports `manual_intervention_required`, do not continue the automated loop until the reported ambiguity, stale review, missing validation, retry limit, or scope problem is resolved.

Use `ai/commands/orchestrator-next.sh` when a human or agent needs the next handoff. It consumes `workflow-state.sh` and prints the standard handoff fields with safe exact commands where possible.

## Chunk Autopilot Summary

When running an approved work package through Chunk Autopilot, Orchestrator's final or stop summary must include chunks completed, commits made, chunks remaining, QA results, validation results, cleanup results, stop reason, and whether final human review is required before merge/release.