# Workflow Handoff Contract Use this standard whenever a role, helper, or workflow step hands work to another role or back to a human. The handoff must make the next step explicit enough that the recipient can continue without asking what command, prompt, or approval is needed. ## Standard Block ```md ## Handoff - Canonical State: - Gate Checked: - Result: - Blockers: - Recommended Next Action: - Immediate Next Step: - Human Review Command: - Prompt Handoff Command: - Transition Command: - Post-Approval Command: - Autopilot Continuation: - Trusted Daemon Git Commands: - Optional Prompt Review Command: - Human Approval Needed: ``` ## Field Rules - `Canonical State`: Use the state names from `ai/standards/workflow-state.md` when a state helper applies. Use `not_applicable` only for pure intake text that is not in a lifecycle file yet. - `Gate Checked`: Name the readiness or review gate used, such as `workflow-state --ready-for-qa`, `workflow-state --ready-to-complete`, `requirements-state`, `requirements-gates`, or `none`. This is evidence, not necessarily the next command to run. - `Result`: Use `passed`, `blocked`, `needs_review`, `needs_implementation`, `ready_to_complete`, `commit_ready`, or another short factual result. - `Blockers`: Use `None.` or list the concrete blockers that must be resolved before the next workflow step. - `Recommended Next Action`: State exactly what should happen next in workflow terms. - `Immediate Next Step`: State the next human or agent action before any approval-dependent command. - `Human Review Command`: Provide the safe read-only command for human inspection when one applies. Use `not_applicable` when no human review command exists. - `Prompt Handoff Command`: Provide the prompt-generation command when the next action is a role handoff, such as `ai/commands/prompt-synthesize.sh qa`. Use `not_applicable` when no prompt handoff applies. - `Transition Command`: Provide the command that actually advances lifecycle state. Use `not_applicable` when no lifecycle transition is available yet. - `Post-Approval Command`: Provide the transition command or command chain that may run only after required human approval. Use `not_applicable` when no approval-gated transition exists. - `Autopilot Continuation`: When Chunk Autopilot is enabled or applicable, state what the Orchestrator should do after the approval/transition succeeds. Use `not_applicable` when no queue continuation applies. - `Trusted Daemon Git Commands`: Provide `git_add_approved` and `git_commit` daemon requests for approved staging/commit work. Raw `git add` and `git commit` are not the normal Codex path when the daemon is available. - Missing Action Summary: When a needed local/dev/runtime action is not registered with the trusted daemon, include `ai/tools/missing-actions/summary.sh` and the missing action id in the handoff. - `Optional Prompt Review Command`: Include when a prompt can be reviewed by Prompt Synthesizer before handoff, such as `ai/commands/prompt-synthesize.sh review qa`. Omit when not applicable. - `Human Approval Needed`: Use `yes` or `no`, plus a short reason when approval is required. When handing off an active chunk, the handoff assumes `## Acceptance Criteria Verification` is current. If it is missing, stale, unmarked, or contains `Blocked` items, report the issue as a blocker instead of recommending QA PASS or completion. ## Role Expectations - Requirements Intake uses the handoff to tell whether the draft needs user clarification or requirements review. - Requirements Review uses the handoff to tell whether requirements can be approved and planned, or which questions block approval. - Chunk Planner uses the handoff to tell whether chunks are ready for orchestration. - Developer uses the handoff to tell whether the chunk is ready for QA and references `ai/commands/workflow-state.sh --ready-for-qa`. - QA uses the handoff to tell whether the chunk is blocked or ready for completion and references `ai/commands/workflow-state.sh --ready-to-complete`. - Orchestrator uses the handoff to make completion, retry, manual intervention, and commit decisions. - Approved work-package handoffs should identify whether Chunk Autopilot is enabled, the approved chunk queue, configured stop milestones, and the final human review boundary. ## Command Selection Use these command categories consistently: - Gate Command: a readiness or review check, such as `ai/commands/workflow-state.sh --ready-to-complete`. - Human Review Command: a read-only inspection command, such as `ai/commands/workflow-summary.sh`. - Prompt Command: a prompt-generation command, such as `ai/commands/prompt-synthesize.sh qa`. - Transition Command: a command that changes lifecycle state, such as `ai/commands/complete-chunk.sh `. - Post-Approval Command: a transition command or command chain that may run only after required human approval. - Autopilot Continuation: post-approval continuation under the canonical full-show lifecycle in `ai/standards/chunk-autopilot.md`. `Gate Checked`, `Human Review Command`, `Prompt Handoff Command`, `Transition Command`, `Post-Approval Command`, and `Autopilot Continuation` are different fields: - Use gate commands such as `ai/commands/workflow-state.sh --ready-for-qa` to describe the readiness check that already ran or should be run before a transition. - Use prompt handoff commands such as `ai/commands/prompt-synthesize.sh qa` when the next workflow step is a role handoff. - Use `ai/commands/workflow-summary.sh` as a human review/read-only command. It is not a lifecycle transition command. - For `ready_for_qa`, the gate is `ai/commands/workflow-state.sh --ready-for-qa`, but the prompt handoff command is `ai/commands/prompt-synthesize.sh qa`. - For `qa_blocked_fixable`, the prompt handoff command is `ai/commands/prompt-synthesize.sh dev-fix`. - For `qa_blocked_requires_decision`, `qa_blocked_scope_change`, or `retry_limit_reached`, the human review command should be `ai/commands/workflow-summary.sh` and human approval is required. - For `developer_pass`, the prompt handoff command is `ai/commands/prompt-synthesize.sh dev` when safe. - For `ready_to_complete` with human review required, the immediate human review command may be `ai/commands/workflow-summary.sh`; the transition/post-approval command must use `ai/tools/operator-daemon/request-action.sh --action complete_chunk --target ` when the trusted daemon is available. - Do not recommend raw `complete-chunk.sh` as the approval path. - For `ready_to_complete`, do not imply `ai/commands/workflow-summary.sh` is the lifecycle transition. It is a review command only. - For `ready_to_complete` under approved Chunk Autopilot, the post-approval continuation is to complete/archive the chunk, perform safe staging/commit when policy allows, and proceed to the next approved queued chunk unless a configured stop condition or final work-package review boundary applies. - Readiness gate commands must not be repeated as the immediate next command when the gate has already passed and human review is required. - For `commit_ready`, prefer trusted daemon registered actions: `ai/tools/operator-daemon/request-action.sh --action git_add_approved --files ""` and `ai/tools/operator-daemon/request-action.sh --action git_commit --message ""`. Do not request Codex platform escalation for those registered actions. Do not run `ai/tools/operator-daemon/run-once.sh` as a shortcut; Codex must create the request and wait for the trusted daemon result. If `ai/tools/operator-daemon/status.sh` reports the trusted Git runtime is unavailable, stop and report that the operator daemon must be running from the trusted local operator shell/tmux; do not fall back to Codex platform approval. If a needed recurring action has no daemon action, use operator Q&A to notify the operator and document the daemon-action gap instead of recommending raw shell as the default path. Register the gap with `ai/tools/missing-actions/register.sh` and include `ai/tools/missing-actions/summary.sh` in the handoff. - If an advisory action is not registered with the daemon and will require Codex platform/tool escalation, provide `ai/commands/platform-escalation-preflight.sh --target unregistered-action --platform-action ""` before requesting the platform prompt. A denied `platform-tool` approval blocks the escalation request. - For an approved work package with Chunk Autopilot enabled, the next command/action is the Orchestrator autopilot run over the approved queue, not a manual per-chunk prompt. If no stop milestones are configured, do not present internal milestone labels as stop commands. ## Legacy Field Compatibility Older chunks, reports, or helper output may still contain legacy `Exact Next Command` or `Immediate Next Command` fields. New handoffs must prefer the explicit command categories in the standard block above. If a legacy field appears, interpret it only in context; `ai/commands/workflow-summary.sh` must never be represented as the lifecycle transition command. Common safe commands for handoffs: ```sh ai/commands/requirements-state.sh ai/commands/prompt-synthesize.sh qa ai/commands/prompt-synthesize.sh review qa ai/commands/prompt-synthesize.sh dev ai/commands/prompt-synthesize.sh review dev ai/commands/prompt-synthesize.sh dev-fix ai/commands/prompt-synthesize.sh review dev-fix ai/commands/workflow-state.sh --ready-for-qa ai/commands/workflow-state.sh --ready-to-complete ai/tools/operator-daemon/request-action.sh --action complete_chunk --target ai/tools/operator-daemon/request-action.sh --action git_add_approved --files "" ai/tools/operator-daemon/request-action.sh --action git_commit --message "" ai/tools/operator-daemon/wait-result.sh ai/commands/platform-escalation-preflight.sh --target unregistered-action --platform-action "" git status --short --untracked-files=all git diff --stat ``` ## Safety Rules - Handoffs prepare or recommend actions; they do not authorize scope expansion. - Handoffs must not include secrets, tokens, `.env` values, or arbitrary file content. - Handoffs must not tell users to run arbitrary shell commands from untrusted input. - If the helper state and markdown notes disagree, set `Human Approval Needed: yes` and recommend manual intervention. ## Remote Operator Notifications Canonical operator Q&A rules live in `ai/standards/operator-questions.md`. Trusted daemon action rules live in `ai/standards/trusted-operator-daemon.md`. Informational notification rules live in `ai/standards/operator-notifications.md`. Top-level runtime operating procedure rules live in `ai/standards/runtime-sop.md`. Close/commit wording and operator-facing docs/help synchronization rules live in `ai/standards/runtime-tooling-governance.md`. Approval validity and resume safety are owned by `ai/standards/operator-questions.md`. Handoffs must not imply that an old approval can be reused automatically. If a prior approval exists, inspect `ai/tools/operator-questions/list-approved-actions.sh` and run the dispatcher dry-run with `ai/tools/approved-action-dispatcher/dispatch.sh --dry-run --once --question-id ` before recommending execution. Stale approvals require a fresh question. Codex I/O bridge wakeups are not an approved-action execution path. If the operator asks to "complete and commit", "close and commit", "commit this", or equivalent orchestration-completion wording, handoffs must treat that as a request to create one fresh `close_commit` approval for the current reviewed state. Execution remains dispatcher-owned and must not be represented as raw Git, Codex platform escalation, or Codex wake/resume continuation. Handoffs must not recommend creating a new chunk when the latest relevant active chunk can be continued. If a new chunk was created, the handoff must state the explicit operator request, unrelated-active-chunk rationale, lifecycle policy reason, or canonical chunk creation gate that allowed it. Handoffs should reference that standard whenever a next step requires human input. In particular, any local human question must go through `ai/tools/operator-questions/ask.sh`; local and Telegram answers are alternative inputs to the same question. Do not use ad hoc `create-checkpoint.mjs` calls for operator questions in handoffs. When an orchestration run finishes, stops, or discovers a design-significant insight, follow `ai/standards/runtime-sop.md` and `ai/standards/operator-notifications.md`. Final local run summaries and Telegram `/details` should use the SOP's canonical run-summary structure instead of duplicating a separate template here.