# Approvals ## Open an approval 1. Open the approval at `//approvals/APPROVAL_ID`. The decision controls sit in the card's footer drawer, titled by the case. 2. Use the ‹ › buttons to move between approvals. A task has its own page at `//tasks/TASK_ID`. ## Send a task back 1. Open the drawer entry. "Send back to …" re-runs the agent at the task's current step, and "Send to …" moves the task. A workspace card names its pass. 2. Type guidance in the box. The button stays disabled until the box has text, except for a follow-up redraft (changed rows are enough) and a send-back that carries answered questions (the answers are enough). 3. Click the final button. Its label ends "with guidance", or "with your answers" or "with my revisions" when it carries answered questions or row rulings. 4. When a plan, refinement or acceptance criteria comes back revised, the section "Last approval round → current" shows what changed since your last decision. A revised breakdown marks each piece added, changed, moved or unchanged under "Last approval round → current round" and lists dropped ones. A first round shows it all. ## Add an optional note or guidance 1. An action with optional text is listed once. Its entry opens a step whose box is marked "Note (optional)" or "Guidance (optional)", above the action's own button. 2. Leave the box empty and click the button to act without it. A note stays in the card's history. Guidance is read by the next agent. ## Answer carried questions 1. If the card shows questions, answer each with an option or free text in the card body, before using any footer button. 2. Until then the footer shows "Answer the open questions above first.", and counts progress with "to go". Every response is disabled. 3. With all answered, the footer names the response the answers lead to, such as "Send back to …" ending "with your answers". Its step offers an optional overall-guidance box. 4. A card that only carries questions offers "Send answers to ", in one click or with guidance. ## Write guidance text 1. Guidance goes to the seat that runs next, not to Autopilot. Make it a direct instruction: state the decision and the reason in one sentence. 2. Name the concrete change or focus: files, acceptance criteria, what to drop. For a timeout, shrink the scope and ask for a check-in. 3. Never paste secrets, tokens, or links that carry credentials. ## refine.accept: Decide this refinement Accept it into planning or backlog. - "Accept and start planning". For a task filed to be built, or a P0. A backlog-bound task and a revision change the wording. - "Send to …" (text: required). Moves the task there with a reason; Refine does not re-run. - "Send back to Refine…" (text: required). Re-runs the agent with your guidance. - "Send to Research…" (text: optional) - Answer carried questions in the card body first. ## breakdown.accept: Decide this breakdown Approve how a large task splits. - "Approve breakdown". Set each piece's priority and build-or-queue route. Children and carried answers apply together; retrying preserves dependencies removed afterward. - "Send back to Breakdown…" (text: required). Re-runs the agent with your guidance. - "Not a split — send to Refine…" (text: required). A failed decline keeps the task and decision unchanged. - "Send to Research…" (text: optional) - Answer carried questions in the card body first. ## plan.approve: Decide this plan Approve a plan so the task starts building. - "Approve plan". The label also mentions revised criteria when the plan carries an acceptance rider. - "Send to Planning…" (text: required) - "Send back to Planning…" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## pr.merge: Decide this merge Merge a finished pull request. - "Merge now". Ratifying performs the merge. Absent while GitHub reports a conflict. - "Send to Build to rebase…" (text: prefilled). Prefilled with a short rebase instruction. Offered while GitHub reports a conflict, and with a refusal. - "Send to …" (text: required). Re-runs the agent with your guidance. - "Simulate CI" When the variant is conflicted: - "Send to Build to rebase…" (text: prefilled). Prefilled with a short rebase instruction. Offered while GitHub reports a conflict, and with a refusal. - "Send to …" (text: required). Re-runs the agent with your guidance. - "Simulate CI" When the variant is checks_unreadable: - "Merge now". Ratifying performs the merge. Absent while GitHub reports a conflict. - "Send to Build to rebase…" (text: prefilled). Prefilled with a short rebase instruction. Offered while GitHub reports a conflict, and with a refusal. - "Send to …" (text: required). Re-runs the agent with your guidance. - "Simulate CI" - "Check again". Only when checks are unreadable. - Answer carried questions in the card body first. ## deploy.release: Decide this release Release merged work to production. - "Approve release" - "Send to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## backlog.prioritize: Choose its priority Set a backlog task's priority. - apply the proposed priority - send back for another proposal (text: required). Re-runs the agent with your guidance. ## sprint.plan: Decide this sprint plan Commit the proposed Soon and Next sprints. - "Apply sprint plan" (text: optional). Also listed with an optional note. - "Send back to Sprint planning…" (text: required). Re-runs the agent with your guidance. ## ideas.promote: Decide which ideas advance Choose which ideas move into the factory. - promote the chosen ideas - send back to Promote (text: required). Re-runs the agent with your guidance. ## ideas.groom: Decide this grooming proposal Apply or decline an Ideas grooming proposal. - apply the grooming proposal - send back to Ideas grooming (text: required). Re-runs the agent with your guidance. ## guidance.file: Decide this guidance update File a guidance task from logged guidance gaps. - "File guidance task (consumes N)" (text: optional). Also listed with an optional note. - "Send back to Guidance review…" (text: required). Re-runs the agent with your guidance. ## harness.file: Decide this harness fix File a fix for a recurring problem in the factory's work. - "File harness-fix task (cites N records)" (text: optional). Also listed with an optional note. - "Send back to Feedback review…" (text: required). Re-runs the agent with your guidance. ## task.supersede: Decide this replacement Replace a task with a newer one. The successor, transferred relationships, carried answers and closure commit together; a failed settlement leaves them unapplied. - approve the replacement - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## task.already-built: Decide how to close this Close a task whose work already exists. Answering this verdict's questions sends it back for another pass. Closure and obsolete-question cleanup commit together; a failed settlement leaves them unapplied. - "Approve & close as already built" - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## dedup.resolve: Resolve these duplicates Decide what to do with tasks that look like duplicates. Answers, survivor changes, relationships and the decision commit together; a failed settlement leaves them unapplied. Close-as-duplicate requires carried questions to be answered first. - merge into existing work - mint one new task - close as duplicate. Appears once the proposed survivor has closed. - "Not duplicates — send back to Dedupe…" (text: required) When the variant is close-covered-by-terminal-survivor: - close as duplicate. Appears once the proposed survivor has closed. - "Not duplicates — send back to Dedupe…" (text: required) - Answer carried questions in the card body first. ## acceptance.revise: Decide these acceptance criteria Approve revised acceptance criteria. - "Approve revised criteria" - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## parked.recheck-item: Decide this parked task Rule on whether a parked task can move again. Carried answers, the ruling and any move commit together; a failed settlement leaves them unapplied. - "Unpark to Roadmap" (text: optional) - "Unpark to Triaging" (text: optional) - "Leave parked" (text: optional) - Answer carried questions in the card body first. ## triage.admit: Decide where this work belongs Decide whether new work is admitted. A rejection and its carried answers commit together; a failed settlement leaves them unapplied. - "Accept into refinement…" (text: optional) - "Reject — close it…" (text: required) - "Not yet — back to Roadmap…" (text: required) - "Blocked — park it…" (text: required) - "Send to Human To Do" - "Send back to Admit…" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## implement.blocked-on-work: Resolve this build blocker A build waits on other work. - continue the build - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## implement.exhausted: Choose how the build recovers The build ran out of rounds, or QA could not run checks. Filed deferrals, carried answers and the decision commit together; a failed settlement leaves them unapplied. - "Send back to Review… / Send back to QA check…" (text: required). Re-runs that seat; no code change. - "Send to …" (text: optional). One click starts a fresh build round; the guidance entry adds text. - "Ship it anyway…" - Answer carried questions in the card body first. ## research.continue: Decide whether research continues Choose whether a research step keeps going. Continuing commits the research answers and carried answers with the decision; a failed settlement leaves them unapplied. - continue research - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## questions.answer: Answer the questions above Answer questions an external wait raised. - "Send answers to " (text: optional). One click, or the entry that adds guidance. - Answer carried questions in the card body first. ## pr.two-open: Reconcile the pull requests Two pull requests are open for one task. - keep the chosen pull request ## pr.closed: Resolve the closed pull request The task's pull request was closed. Carried answers and recovery commit together; a failed settlement leaves them unapplied. - rebuild the change - abandon the task - Answer carried questions in the card body first. ## pr.unreachable: Resolve the unreachable pull request GitHub cannot be reached for the pull request. - check the pull request again ## pr.merge-mismatch: Resolve the merge mismatch The pull request merged a different head. Carried answers, recovery and any merge confirmation commit together; a failure leaves them unapplied. - accept the merged head - rebuild the change - "Acknowledge" - abandon the task - Answer carried questions in the card body first. ## followups.file: Decide these follow-ups File deferred work from a task or its card, with links and answers. - "File N · decline M" (text: optional). No PR or origin move is needed. - "Send follow-up changes to Redraft…" (text: required). Re-runs the agent with your guidance. ## done.review: Decide the done review Dismiss finished cards from the board. - dismiss the finished cards ## parent.progress: Review the stalled parents Parents are waiting on tasks that haven't moved in 7 days. - leave the parents for 7 days. Leave this parent hides one row; Leave all closes the card. - start planning - move - close ## ci.simulation-report: Decide this CI result A CI simulation finished. - "Acknowledge report" ## parked.staleness: Decide this stale task A parked task has sat for a long time. Recheck commits its queued run with your answers and ruling before starting. A failure leaves them unapplied. - recheck the parked task - dismiss the card ## factory.stalled: Review the factory stall Factory work has stalled. - "Acknowledge stall" ## deploy.behind: Review what is not deployed Production is behind the merged code. - "Acknowledge". Nothing to decide; it closes by itself when production catches up. ## base.red: Review the failing base branch Checks are failing on the base branch. Each check decision saves with its fix task or linked task changes; a failed save keeps the whole decision unchanged. Deciding one check leaves this card open. - settle each check - "Acknowledge". It returns if a task or main check reports it again, and closes once main passes. ## write-scope.notice: Review the unexplained change A shared repository changed and no task is blamed. - "Acknowledge" ## shaping.stale: Get this plan building again A plan can no longer start building. - "Plan it again". Offered when the approval was not recorded, the task was reshaped, or the plan changed. - "Send to refinement" (text: optional). Always offered; the only lever when the task was edited, moved repository, or never refined. Also offered with guidance. - "Acknowledge" ## input.required: Provide the required input An agent needs an answer to continue. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## plan.split-suggested: Shape it first, or build it as one Planning found several tasks in one. - "Send to refinement to shape first" (text: optional). Also offered with guidance. - "Build it as one" - Answer carried questions in the card body first. ## plan.route-suggested: Choose where planning should continue Planning suggests a better route. - take the suggested route - keep planning (text: optional) - Answer carried questions in the card body first. ## dedup.clarify: Clarify these duplicates Say whether two tasks are duplicates. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## acceptance.conflict: Resolve this acceptance conflict Pick which acceptance criteria apply. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## implement.handoff-exhausted: Choose how the handoff recovers The build handoff loop did not converge. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## implement.blocked: Resolve this blocked build A build cannot continue. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## task.no-code-needed: Decide how to close this A task needs no code change. This decision and its carried answers commit together; a failed settlement leaves them unapplied. - close as no code needed - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## task.already-landed: Decide the empty diff The work already landed. Answer carried questions before either response. Those answers, the decision and movement commit together; a failed settlement leaves them unapplied. - "Advance to release queue" - "Send to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## deploy.continue: Choose how deployment continues A rollout needs a decision. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## run.timeout: Choose how the run recovers A run ran out of time. Splitting or skipping research commits the question changes and decision together. A failure leaves them unapplied; success leaves Research queued for the scheduler. - "Retry with a smaller scope…" (text: required). Pick a suggested reduction or write one; the text rides as guidance. - "Split into smaller questions" - "Skip" - Answer carried questions in the card body first. ## run.failure: Choose how the run recovers A run failed; answering releases the retry. - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is worktree_dirty, stray_writes, worktree_recovery_failed: - "Commit stray changes as wip" - "Discard stray changes" - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is oom, oom_in_turn, oom_pool_starved, oom_escalated: - "Try again with N GiB" - "Retry at the same cap (N GiB)" - retry at a chosen size - "Let the governor decide" - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is ambiguous_repo: - scope the run to one repository. The repository choice, carried answers and decision commit together. A failed settlement leaves them unapplied. - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is verdict_rule_violation: - withdraw the change request. Cancellation, carried answers and the decision commit together. A failed settlement leaves them unapplied. - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is subscription_hold: - "Release a retry" - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is codex_refresh_reused, agent_account_authentication_rejected: - sign in again. Starts the account's sign-in. - "Send back to …" (text: required). Say what changed, such as an image rebuilt on the host. When the variant is stale_shaping_basis: - send to refinement. The only arm for a stale plan basis. - Answer carried questions in the card body first. ## run.incident: Review this workspace incident A workspace-wide incident needs a look. Answer any carried questions before deciding. The answers, decision and matching task-card releases commit together. A failed settlement leaves the answers and releases unapplied. - "Acknowledge" When the variant is subscription: - release the held tasks ## task.change-review: Decide these requested changes Apply or decline a requested change to a task. Applying or requesting a fresh review commits with carried answers; a failure keeps them open. - apply the requested changes - send back for another draft (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## repo.environment-change: Decide this environment change Approve a repository environment change. - approve the environment change. Approves the definition shown. A failed save starts no build. - "Send back to …" (text: required). Re-runs the agent with your guidance. ## repo.environment-branch-build: Approve or refuse this branch's sandbox Approve building a branch's sandbox before merge. - approve the sandbox build. Approves the definition shown. A failed save starts no build. - refuse the sandbox build (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first. ## repo.environment-needs: Decide these environment needs Rule on what the step's environment may contain. Rulings, any remedy task, guidance and hold release save together; a failed settlement keeps the decision unchanged. Releasing waiting tasks leaves undecided needs open. - apply the per-row rulings - release the waiting tasks ## tree.hold: Choose how the rest of this tree continues A task tree reached its size limit. Either ruling commits with its carried answers and decision; a failed settlement keeps the tree held and the questions open. - let breakdown continue - stop splitting - Answer carried questions in the card body first. ## dependency.clash: Choose how this task waits for its dependencies A task set to build after shaping depends on queued work, so it waits here instead of in Planning. Carried answers save with the route or link decision; a failed save leaves them unapplied. - "Pull the dependencies forward". Everything the task waits on builds after shaping. Roadmap ideas move to the factory floor. - "Queue this task behind them". Once the work above lands, the task is planned normally. - "The dependency isn't real". Offered on each dependency row; it removes that link. - Answer carried questions in the card body first. ## pipeline.audit: Fix tasks queued behind their own dependencies These tasks sit ahead of work they depend on. Nothing moves until you pick a fix. - "Apply a fix to a row". Moves the tasks in one step and clears that row. A fix that would break the order is refused. - "Close the card". Rows left alone stay as they are on the board. ## agent.failover: Choose how subscription work continues A subscription ran out of usage or disconnected. - "Wait for reset". Not offered when the connection is broken. - "Use fallback" When the variant is disconnected: - stay on the root account. A broken connection has no window to wait out. - "Use fallback" ## adhoc: Choose a response An agent asked for direction. - "Send back to …" (text: required). Re-runs the agent with your guidance. - Answer carried questions in the card body first.