ace-assign 0.42.4 → 0.55.0

data/handbook/workflow-instructions/assign/drive.wf.md

@@ -1,10 +1,19 @@
 ---
+name: assign-drive
+description: Drive an ace-assign assignment until completion or an explicit blocker.
+allowed-tools:
+- Bash(ace-assign:*)
+- Bash(ace-bundle:*)
+- Read
+- Write
+- AskUserQuestion
+- Skill
 doc-type: workflow
 title: Drive Assignment Workflow
 purpose: workflow instruction for driving ace-assign assignment execution
 ace-docs:
-  last-updated: 2026-03-18
-  last-checked: 2026-03-21
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # Drive Assignment Workflow
@@ -16,7 +25,7 @@ Drive agent execution through an active assignment by continuously checking stat
 ## Prerequisites
 
 - An active assignment exists (created via `ace-assign create` or `/as-assign-create`)
-- Assignment has at least one pending or in_progress step
+- Assignment has at least one pending or active step
 
 ## Assignment Context Propagation
 
@@ -27,11 +36,11 @@ When working with multiple concurrent assignments, the active assignment is reso
 3. `.latest` symlink (auto-updated on any activity)
 4. Scan all assignments (fallback)
 
-If this workflow is invoked with an argument (for example `/as-assign-drive abc123@010.01`), treat that value as the initial assignment target. If no argument is provided, resolve one active assignment and pin it for the entire loop.
+If this workflow is invoked with an argument (for example `/as-assign-drive abc123@010.01`), treat that exact value as the initial assignment target. If no argument is provided, resolve one active assignment and pin it for the entire loop.
 
 ```bash
-# Set once from workflow argument (empty when not provided)
-ASSIGNMENT_TARGET="${1:-}"
+# Set once from workflow argument or internal scoped default (empty when neither is provided)
+ASSIGNMENT_TARGET="${1:-${ACE_ASSIGN_DEFAULT_TARGET:-}}"
 
 # Resolve and pin assignment identity for the full drive loop
 if [ -n "$ASSIGNMENT_TARGET" ]; then
@@ -50,6 +59,8 @@ if [ -z "$ASSIGNMENT_TARGET" ]; then
 fi
 ```
 
+`ACE_ASSIGN_DEFAULT_TARGET` is an internal fallback passed by `fork-run` launches. If it is present, use it exactly. Do not widen it back to the parent assignment, do not drop the `@<root>` scope suffix, and do not re-resolve an unscoped assignment target later in the loop.
+
 ### Explicit Assignment Targeting (Recommended)
 
 Use explicit flags to propagate assignment context across subprocesses and tools:
@@ -72,7 +83,7 @@ ace-assign status --assignment abc123@010.01
 ace-assign finish --message done.md --assignment abc123@010.01
 ```
 
-When an assignment target includes scope (`<id>@<root>`), `ace-assign finish --message` advances only within that subtree and stops when the subtree is complete.
+When an assignment target includes scope (`<id>@<root>`), `ace-assign finish --message` finishes only within that subtree. Pending descendants remain pending until scoped execution explicitly starts them.
 
 Helper command:
 
@@ -104,12 +115,57 @@ ace-assign finish --message done.md --assignment <id>
 
 Repeat the following cycle until all steps are done or failed:
 
+### Run-Until-Blocked Contract
+
+Once `ASSIGNMENT_TARGET` is pinned, keep driving that exact target until exactly one of these stop conditions is true:
+
+1. `ace-assign status --assignment "$ASSIGNMENT_TARGET"` shows all steps complete
+2. A workflow step explicitly requires HITL or other user judgment before execution can continue
+3. A step reaches an unrecoverable failure path and this workflow instructs you to stop
+4. The user explicitly interrupts or cancels execution
+
+Do **not** stop merely because you have useful progress to report.
+
+- Intermediate progress belongs in short progress updates, not in a final completion response.
+- `pending` steps with no active step are not a stop condition. They mean the queue must be advanced and the loop must continue.
+- A batch child subtree finishing is not a completion boundary for the parent assignment.
+- If `ASSIGNMENT_TARGET` includes `@<root>`, that scoped subtree is the entire execution boundary.
+- A paused assignment with remaining runnable work is not "done"; treat it as a recoverable scheduler state and resume the loop.
+
+### Final Response Gate
+
+Before sending any final user-facing completion response, re-run:
+
+```bash
+ace-assign status --assignment "$ASSIGNMENT_TARGET" --format json
+```
+
+You may only stop and send a final response when one of these is true:
+
+- the pinned assignment has no remaining runnable `pending` or `active` work
+- the workflow recorded an explicit blocker or unrecoverable failure stop condition
+- the user explicitly interrupted or canceled execution
+
+Do **not** send a final response merely because:
+
+- one child subtree completed in the parent assignment
+- useful progress was made
+- a prior terminal session ended
+- the parent assignment surfaced the next pending step after active work finished
+
+Concrete example:
+
+- `010.01 done` and `010.02.01 active` means continue driving the assignment. It is not a completion boundary.
+- `040.01 done`, `040.02 done`, and `040.03 done` under `/as-assign-drive <id>@040` means stop the scoped worker. Do not inspect parent step `070` from that scoped process.
+
 ### Step Execution Policy
 
 - Planned steps are mandatory work items. Do not skip them by judgment.
 - For each active step, do exactly one of:
+
   1. Execute the step and report completion with `ace-assign finish --message`
   2. Attempt execution, capture blocker evidence, and mark failed with `ace-assign fail`
+
 - Never use report text to "skip" or synthesize completion for planned steps.
 - **Fork-delegation constraint**: If the active step has `FORK: yes`, the driver MUST delegate via `ace-assign fork-run`. The driver MUST NOT execute fork-marked steps inline, absorb remaining fork children after partial failure, or inject retry steps as top-level siblings. All fork recovery goes through re-fork (see [Fork-Run Crash Recovery](#fork-run-crash-recovery-partial-completion)).
 - **Conditional release in review subtrees**: A `release` step inside a review cycle (e.g., `[review-pr, apply-feedback, release]`) MUST skip the version bump when prior sibling steps produced no code changes. If `apply-feedback` reported no findings or `git diff HEAD~1 --stat` shows only report files, mark release done with "no-op: no changes to release" instead of bumping.
@@ -119,30 +175,40 @@ Repeat the following cycle until all steps are done or failed:
 After completing or failing each step, evaluate whether the assignment needs adaptation:
 
 - **Test failures detected** → Consider adding a fix-tests step:
+
   ```bash
   ace-assign add "fix-tests" --instructions "Fix failing tests identified in step NNN" --assignment "$ASSIGNMENT_TARGET"
    ```
 
+- **E2E failures detected** (`ace-test-e2e` command, `.ace-local/test-e2e/` evidence, or explicit failing scenario IDs) → add an E2E-specific fix step instead of generic `fix-tests` / `fix-issue`:
+
+  ```bash
+  ace-assign add "fix-e2e" --instructions "Use /as-e2e-fix for the failing package and scenario IDs from the recorded evidence. If analysis is missing, let /as-e2e-fix generate it via wfi://e2e/analyze-failures before applying fixes. Re-run the targeted failing scenarios before completing this step." --assignment "$ASSIGNMENT_TARGET"
+  ```
+
 - **Review found critical issues** → Consider adding an apply-critical-fixes step:
+
   ```bash
   ace-assign add "apply-critical-fixes" --instructions "Address critical review findings before proceeding" --assignment "$ASSIGNMENT_TARGET"
   ```
 
 - **Missing prerequisite discovered** → Consider adding the prerequisite step:
+
   ```bash
   ace-assign add "missing-prereq" --instructions "Complete prerequisite work discovered during step NNN" --assignment "$ASSIGNMENT_TARGET"
   ```
 
-- **Metadata hint**: Step file contains `trigger_on_failure` — if the step failed, inject the referenced step type
+- **Metadata hint**: Step file contains `trigger_on_failure` -- if the step failed, inject the referenced step type
 
 Use `decision_notes` from step metadata (if present) as additional guidance for these assessments.
 
 - **Review-cycle circuit breaker**: When a review fork subtree fails due to provider unavailability (not code bugs), evaluate whether to attempt the next review cycle:
+
   - If the **first** review cycle (valid) failed on providers: skip remaining cycles (fit, shine). Mark them done with "skipped: provider unavailable for prior cycle" reports.
   - If the **second** cycle (fit) failed after valid succeeded: skip shine. Valid already captured correctness issues.
   - **Never retry a provider-failed review cycle more than once.** If the re-fork also fails on providers, mark the cycle done-with-skip and move on.
 
-- **Transient network failure retry**: When a fork subtree fails due to a transient network error (connection reset, DNS timeout, socket hangup) — as opposed to provider unavailability or auth failure — wait 30 seconds and re-fork once. If the re-fork also fails on a network error, treat it as a hard failure and apply the circuit breaker rules above. Auth errors (401/403) and not-found errors (404) are never transient — fail immediately on those.
+- **Transient network failure retry**: When a fork subtree fails due to a transient network error (connection reset, DNS timeout, socket hangup) -- as opposed to provider unavailability or auth failure -- wait 30 seconds and re-fork once. If the re-fork also fails on a network error, treat it as a hard failure and apply the circuit breaker rules above. Auth errors (401/403) and not-found errors (404) are never transient -- fail immediately on those.
 
 ### 1. Check Status
 
@@ -152,14 +218,20 @@ echo "$STATUS_OUTPUT"
 ```
 
 Read the output to identify:
+
 - Assignment ID (must remain equal to pinned `ASSIGNMENT_ID`)
-- Current step number, name, and status
-- Current step's instructions
-- Current step's skill reference (if any)
-- Remaining steps in the queue
+- Active step list in scope, or next step when nothing is active
+- Remaining visible steps in the queue preview
+- Hidden-step counts for large queues
 
 **Note:** `ace-assign status` is the source of truth for assignment state. The step files in the `steps/` directory are the backing store, but always query status via the command for accurate information.
 
+Load instructions separately when needed:
+
+```bash
+ace-assign step --assignment "$ASSIGNMENT_TARGET"
+```
+
 ### 2. Auto-Delegate Fork Subtrees (When Applicable)
 
 Before executing the current step inline, check whether the active step is inside a fork-enabled subtree.
@@ -184,6 +256,20 @@ fi
 
 This prevents fork agents from stalling on pre-existing unrelated changes. Assignment metadata files (`.ace-local/`, `.ace-tasks/`, `.ace-retros/`) are expected to be dirty during drive execution and are excluded.
 
+Dirty-tree classification rule:
+
+- Do not auto-commit every unrelated dirty path.
+- First classify the dirty state:
+  - **intentional work**: user edits, task implementation, or other meaningful repo changes that must be preserved
+  - **generated side effects**: bootstrap/config scaffolding, handbook projection output, caches, or other machine-generated files outside the current task scope
+- If the dirty paths are intentional work, preserve them and either continue with scope awareness or commit them deliberately.
+- If the dirty paths are generated side effects outside the current task scope, clean/reset them before `fork-run` instead of committing them.
+- Only stop for user input when classification remains ambiguous after inspection.
+
+Example:
+
+- A bulk untracked `.ace/...` tree created by `ace-config sync` is generated side-effect output. Clean it; do not create a "pre-fork" commit for it.
+
 #### Delegation Rule
 
 **FORK SIGNAL**: If a step row shows `yes` in the `FORK` column, the step itself has `context: fork` and MUST be delegated via `fork-run`.
@@ -194,6 +280,7 @@ This prevents fork agents from stalling on pre-existing unrelated changes. Assig
 | `FORK: ` (empty) | Step is not fork-enabled | Execute inline (or inspect fork-enabled children if batch parent) |
 
 **Example status output:**
+
 ```
 NUMBER       STATUS       NAME                           FORK   CHILDREN
 ------------------------------------------------------------------------------
@@ -202,6 +289,7 @@ NUMBER       STATUS       NAME                           FORK   CHILDREN
 ```
 
 Step 020 shows `FORK: yes` → run:
+
 ```bash
 ace-assign fork-run --assignment <id>@020
 ```
@@ -209,8 +297,15 @@ ace-assign fork-run --assignment <id>@020
 **Delegation boundary rule**
 
 - Outside a delegated fork scope, do NOT execute fork steps inline.
-- If status output is already scoped to `Current Step: <root>.*` via `--assignment <id>@<root>`, the fork boundary is already entered: continue inline and never call `fork-run` again for the same `<root>`.
-- If the current step is a top-level step with `FORK: yes` and no matching scope is active, delegate immediately.
+- First decide whether the fork boundary is already entered before issuing `fork-run`.
+- If scoped status for `--assignment <id>@<root>` already resolves work inside `<root>`, the fork boundary is already entered: continue inline and never call `fork-run` again for the same `<root>`.
+- A same-root call to `ace-assign fork-run --assignment <id>@<root>` from inside that exact scoped subtree is invalid and must be treated as an error, not a retry path.
+- If the scoped root itself is active and no child in that subtree is active yet, run:
+
+  - `ace-assign start --assignment "$ASSIGNMENT_TARGET"`
+
+- After a child step inside the scoped subtree becomes active, continue executing that child inline within the same scope.
+- Only if the current step is a top-level step with `FORK: yes` and no matching scope is already active should the driver delegate via `fork-run`.
 
 #### Nested Batch Containers (Container → Fork Children)
 
@@ -222,10 +317,12 @@ A batch container (e.g., `010`) may have children but no fork context itself (`F
 - `fork_retry_limit: <N>` (default `1`)
 
 **How to distinguish:**
+
 - **Direct fork target**: `FORK: yes` on the current step → fork-run the current step.
 - **Batch container**: `FORK: ` on parent, but children include `FORK: yes` steps.
 
 **Pattern for batch containers:**
+
 ```bash
 # Read scheduler metadata from parent step 010
 # parallel=false  => sequential, still fork every child
@@ -236,9 +333,11 @@ A batch container (e.g., `010`) may have children but no fork context itself (`F
 
 - Iterate pending child steps in number order.
 - For each child with `FORK: yes`, run:
+
   - `ace-assign fork-run --assignment <id>@<child>`
+
 - Re-check status after each child.
-- Do not pause for user input between children — treat the batch loop as a single unit (see Batch Continuation Rule below).
+- Do not pause for user input between children -- treat the batch loop as a single unit (see Batch Continuation Rule below).
 
 **Parallel mode (`parallel: true`)**
 
@@ -262,12 +361,19 @@ The driver MUST NOT pause for user input between child fork-runs within a batch
 
 1. Verify the child's reports (see Subtree Guard below).
 2. If reports indicate successful completion, immediately launch the next pending child.
-3. Treat the entire batch loop as a single unit of execution — only pause on quality concerns flagged during report review.
+3. Treat the entire batch loop as a single unit of execution -- only pause on quality concerns flagged during report review.
 4. For timeout-constrained environments: launch `fork-run` in background, poll for completion, then loop to the next child without pausing.
 
+Conversational boundary rule:
+
+- Do not end the turn or emit a final user-facing completion summary after a child subtree unless the entire assignment now satisfies a real stop condition from [Run-Until-Blocked Contract](#run-until-blocked-contract).
+- If child `010.01` completes, reports are clean, and `010.02` is still pending, immediately advance/resume the queue and continue driving.
+- Treat child-subtree completion as progress within the same drive session, not as permission to stop.
+
 **Failure policy (retry-then-stop)**
 
 - On any child failure:
+
   - Pause launching new children immediately.
   - Wait for in-flight children to finish.
   - Retry failed child once (`fork_retry_limit=1` default).
@@ -279,11 +385,29 @@ The driver MUST NOT pause for user input between child fork-runs within a batch
 ```bash
 STATUS_JSON=$(ace-assign status --assignment "$ASSIGNMENT_TARGET" --format json)
 ASSIGNMENT_ID=$(echo "$STATUS_JSON" | ruby -rjson -e 'puts JSON.parse(STDIN.read).dig("assignment", "id")')
+SCOPED_ROOT="${ASSIGNMENT_TARGET#*@}"
+ACTIVE_STEP=$(echo "$STATUS_JSON" | ruby -rjson -e '
+  scoped_root = ARGV[0].to_s
+  active = Array(JSON.parse(STDIN.read)["active_steps"])
+  child = active.find { |step| step["number"] != scoped_root && step["number"].start_with?("#{scoped_root}.") }
+  puts(child ? child["number"] : active.first&.fetch("number", nil))
+' "$SCOPED_ROOT")
+
+if [ -n "$SCOPED_ROOT" ] && [ "$ACTIVE_STEP" = "$SCOPED_ROOT" ]; then
+  ace-assign start --assignment "$ASSIGNMENT_TARGET"
+  continue
+fi
+
 FORK_ROOT=$(echo "$STATUS_JSON" | ruby -rjson -e '
-  p = JSON.parse(STDIN.read)["current_step"]
-  puts p["number"] if p && p["context"] == "fork"
-')
-if [ -n "$FORK_ROOT" ]; then
+  scoped_root = ARGV[0].to_s
+  active = Array(JSON.parse(STDIN.read)["active_steps"])
+  next_fork = active.find do |step|
+    step["context"] == "fork" &&
+      (scoped_root.empty? || (step["number"] != scoped_root && !step["number"].start_with?("#{scoped_root}.")))
+  end
+  puts next_fork["number"] if next_fork
+' "$SCOPED_ROOT")
+if [ -n "$FORK_ROOT" ] && [ "$FORK_ROOT" != "$SCOPED_ROOT" ]; then
   ace-assign fork-run --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}"
   # Re-check status after subtree delegation completes
   continue
@@ -292,13 +416,103 @@ fi
 
 `fork-run` executes the entire subtree in one dedicated process and returns when the subtree is complete or failed.
 
+#### Fork Wait Continuation Rule
+
+After launching `ace-assign fork-run`, the driver remains inside the same drive session.
+
+- If fork session metadata includes `callback_pane`, callback mode is active. In that case:
+
+  - do not poll the forked subtree on a timer
+  - do not run the `sleep 360` loop
+  - remain idle after launch and wait for the child forked agent to send a final status message back into the origin pane
+  - treat the callback message as the trigger to resume the parent drive loop
+  - if the callback never arrives and the session is resumed later, recover from assignment state and scoped status instead of waiting forever
+
+- Treat "fork subtree is still running" as an internal progress state, not as a stop condition.
+- Do not end the turn, emit a final user-facing completion summary, or hand control back to the user merely because the driver is waiting on fork completion.
+- Poll the forked subtree every 6 minutes by default. Use two signals on each poll:
+
+  1. poll the live fork session/process handle
+  2. poll scoped assignment status with `ace-assign status --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}"`
+
+- Treat scoped assignment status as the source of truth for subtree completion. Terminal PTY output is helpful telemetry, but it is not the canonical completion signal.
+- Continue polling until one of these is true:
+
+  - the `fork-run` process exits
+  - scoped status for the subtree proves every step inside that subtree is terminal (`done` or `failed`)
+  - the workflow reaches a documented blocker or failure path
+
+- If scoped subtree status is terminal, immediately treat the fork as complete even if the PTY stayed quiet or the original terminal handle has already disappeared.
+- A quiet terminal is not a stall by itself. Only treat the fork as stalled when there is no scoped status movement, no new subtree reports, and no process exit for about 30 minutes.
+- When the wait ends, immediately re-enter the parent drive loop. Do not stop between "fork finished" and "next runnable step started."
+
+#### Fork Callback Rule
+
+When `ACE_ASSIGN_CALLBACK_PANE` is present in the forked child environment:
+
+- before stopping for either success or failure, send one final sentence back to the origin pane with direct `ace-tmux send`
+- use the exact pane target from `ACE_ASSIGN_CALLBACK_PANE`
+- use a success sentence shaped like:
+
+  ```bash
+  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} completed. Resume parent assignment drive now." --key Enter
+  ```
+
+- use a failure sentence shaped like:
+
+  ```bash
+  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} failed. Resume parent assignment drive and inspect scoped status." --key Enter
+  ```
+
+- do not invent a new skill or wrapper for this callback; use `ace-tmux send` directly
+
+#### Post-Fork Resume Checklist
+
+Immediately after the fork wait ends, run this checklist in order:
+
+1. If `fork-run` exited non-zero, enter [Fork-Run Recovery](#fork-run-recovery).
+2. Read and review subtree reports.
+3. Check for uncommitted changes and commit safety-net leftovers if needed.
+4. Query parent assignment status.
+5. If no active step exists but pending work remains, run:
+
+   ```bash
+   ace-assign start --assignment "$ASSIGNMENT_TARGET"
+   ```
+
+6. If pending or `active` work remains and no blocker was recorded, continue the main loop immediately.
+7. Only stop if the assignment now satisfies a real stop condition from [Run-Until-Blocked Contract](#run-until-blocked-contract).
+
+#### Scoped Worker Completion Boundary
+
+When `ASSIGNMENT_TARGET` already includes `@<root>`, the current process is the subtree worker, not the parent orchestrator.
+
+- After report review, re-check `ace-assign status --assignment "$ASSIGNMENT_TARGET"`.
+- If that scoped status is terminal, stop immediately.
+- Do not query the parent assignment from that scoped worker.
+- Do not widen a scoped target back to parent assignment status.
+- Do not continue into later sibling roots such as `070` from `/as-assign-drive <id>@040`.
+- Parent resume after subtree completion belongs only to the unscoped driver that launched the fork.
+
+Detached-resume rule:
+
+- If a prior drive session or terminal ended, a new `/as-assign-drive` invocation MUST recover from assignment state, not from the old terminal handle.
+- On re-entry, first inspect parent `ace-assign status --assignment "$ASSIGNMENT_TARGET"` and, when applicable, scoped subtree status for the last in-flight fork root.
+- If the child subtree is already terminal, run the same post-fork checklist immediately and continue the parent queue without waiting for any historical `fork-run` session to be observed again.
+
+Concrete example:
+
+- Incorrect: launch `fork-run` for `040`, post "waiting on subtree", stop responding, and never resume `070`.
+- Correct: launch `fork-run` for `040`, poll until it finishes, review reports, re-check `ace-assign status --assignment "$ASSIGNMENT_TARGET"`, then advance and launch `070` if it is the next runnable step.
+- Correct after interruption: re-run `/as-assign-drive <assignment-id>`, detect that `040` is already terminal from scoped status/reports, then immediately advance and launch `070`.
+
 > **Long-running execution:** `fork-run` typically takes 10-30 minutes depending on subtree complexity. If your environment has bash timeout limits (e.g., Claude Code's 10-minute Bash tool limit), run `fork-run` in background and poll for completion:
 >
 > ```bash
 > # Run fork-run in background (use run_in_background: true in Claude Code)
 > ace-assign fork-run --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}" &
 >
-> # Poll scoped status every 5 minutes until subtree completes
+> # Poll scoped status every 6 minutes until subtree completes
 > while true; do
 >   STATUS_JSON=$(ace-assign status --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}" --format json)
 >   COMPLETE=$(echo "$STATUS_JSON" | ruby -rjson -e '
@@ -307,36 +521,41 @@ fi
 >     puts steps.all? { |step| step["status"] == "done" || step["status"] == "failed" }
 >   ')
 >   [ "$COMPLETE" = "true" ] && break
->   sleep 300
+>   sleep 360
 > done
+> ace-assign status --assignment "$ASSIGNMENT_TARGET"
 > ```
 
 #### Subtree Completion: Task Status Verification
 
 After a fork subtree completes (work-on-task finishes successfully):
 
-1. **Verify ace-taskflow status matches assignment status.** If the assignment shows `work-on-task` as done but ace-taskflow still shows `in-progress`, status drift has occurred.
+1. **Verify ace-task status matches assignment status.** If the assignment shows `work-on-task` as done but ace-task still shows `in-progress`, status drift has occurred.
 
 2. **If mark-task-done step was NOT included in the assignment** (common for ad-hoc assignments):
+
    ```bash
    # Manually sync status before reporting subtree complete
    ace-task done {taskref}
    ace-task {taskref}  # Verify it shows status: done
    ```
 
-3. **Report the subtree complete only after verification.** This prevents the orchestrator from showing work as done while ace-taskflow shows it as in-progress.
+3. **Report the subtree complete only after verification.** This prevents the orchestrator from showing work as done while ace-task shows it as in-progress.
 
 #### Subtree Guard: Review Fork Reports Before Continuing
 
 After fork-run returns and completion is verified, the driver acts as the **guard** for the subtree. Before continuing to the next step:
 
 1. **Read all subtree report files** from `.ace-local/assign/<assignment-id>/reports/`:
+
    ```bash
    # List and read all reports for the completed subtree
    ls .ace-local/assign/${ASSIGNMENT_ID}/reports/${FORK_ROOT}.*
    # Read each report file to review the forked agent's work
    ```
+
 2. **Check for uncommitted changes** left by the fork agent:
+
    ```bash
    DIRTY=$(git status --short)
    if [ -n "$DIRTY" ]; then
@@ -346,7 +565,8 @@ After fork-run returns and completion is verified, the driver acts as the **guar
      ace-git-commit -i "commit changes left by fork subtree ${FORK_ROOT}"
    fi
    ```
-   Fork agents are expected to commit all their work. Uncommitted files indicate incomplete commit discipline — note this when reviewing reports.
+
+   Fork agents are expected to commit all their work. Uncommitted files indicate incomplete commit discipline -- note this when reviewing reports.
 3. **Verify quality**: Check that reports indicate successful completion, not just step advancement.
 4. **Flag concerns**: If any report indicates partial work, errors, or skipped steps, stop and ask the user before continuing.
 5. **Only then continue** the main drive loop to the next step.
@@ -357,12 +577,33 @@ After fork-run returns and completion is verified, the driver acts as the **guar
 
 After all fork subtrees within a batch container complete, the container auto-marks as Done. However, the queue pointer may not automatically advance to the next top-level step.
 
-**After verifying all fork subtree reports**, if `ace-assign status` shows no Active step (all completed steps but no new in-progress step), run:
+**After verifying all fork subtree reports**, if `ace-assign status` shows no active step (all completed steps but no new active step), run:
+
 ```bash
 ace-assign start --assignment "$ASSIGNMENT_TARGET"
 ```
+
 This advances the queue to the next pending top-level step.
 
+If pending steps still remain after this queue advancement, continue the drive loop immediately. Do not stop after printing a partial progress summary.
+
+Concrete example:
+
+```text
+010.01 done
+010.02 pending
+010.03 pending
+Current Step: none
+```
+
+This state means "resume driving", not "return final status". Run:
+
+```bash
+ace-assign start --assignment "$ASSIGNMENT_TARGET"
+```
+
+then continue the loop from status check.
+
 #### Fork-Run Recovery
 
 When `fork-run` exits non-zero, invoke the fork recovery workflow:
@@ -428,9 +669,11 @@ For external-facing steps (for example PR/review/release/push/update lifecycle s
 
 - Attempt the step command(s) first.
 - If blocked, capture concrete evidence:
+
   - command attempted
   - exact error output
   - why the step cannot proceed
+
 - Mark step failed with evidence (do not report synthetic completion).
 
 ```bash
@@ -449,27 +692,35 @@ Use HITL when:
 For a blocked step:
 
 1. Create a HITL event with assignment and step context:
+
    ```bash
    ace-hitl create "Need product decision" --question "Should retries be visible?" --assignment <id> --step <number> --step-name <name> --resume "/as-assign-drive <id>"
    ```
+
 2. Fail the step using canonical stall format:
+
    ```bash
    ace-assign fail --message "HITL: <hitl-id> <hitl-path>" --assignment "$ASSIGNMENT_TARGET"
    ```
+
 3. Human/operator resolves:
+
    ```bash
    ace-hitl show <hitl-id>
    ace-hitl update <hitl-id> --answer "Yes, show retries in user-facing output."
    ace-hitl wait <hitl-id>
    ```
+
 4. Discover pending HITL work:
    - Main checkout default (smart local-first): `ace-hitl list`
    - Explicit scope controls: `ace-hitl list --scope current` and `ace-hitl list --scope all`
 5. Polling is default: requesting agent waits on its own HITL id (`ace-hitl wait <hitl-id>`), not global queues.
 6. Resume dispatch is fallback: if waiter is no longer active, run:
+
    ```bash
    ace-hitl update <hitl-id> --answer "<decision>" --resume
    ```
+
 7. On retry/resume, read the answer from the HITL event and continue normal fail/retry mechanics. Do not introduce gate phases, assignment-level paused state, or extra resume commands in `ace-assign`.
 
 ### 5. Write Report (Only After Real Execution)
@@ -504,6 +755,7 @@ echo "$POST_STATUS"
 ```
 
 Required checks:
+
 - If report succeeded: active step advanced consistently with work performed
 - If fail succeeded: assignment is stalled or moved according to retry/add logic
 - If output mismatches expected transition: stop and ask user before continuing
@@ -533,7 +785,13 @@ Creates a new step linked to the original. Original remains visible as failed.
 ace-assign add "fix-issue" --instructions "Fix the failing tests and verify" --assignment "$ASSIGNMENT_TARGET"
 ```
 
-New step is inserted after the current in-progress step.
+New step is inserted after the current active step.
+
+When the failure evidence is E2E-specific (`ace-test-e2e`, scenario IDs, or `.ace-local/test-e2e/` artifacts), prefer:
+
+```bash
+ace-assign add "fix-e2e" --instructions "Use /as-e2e-fix for the failing package and scenario IDs from the recorded evidence. If analysis is missing, let /as-e2e-fix generate it via wfi://e2e/analyze-failures before applying fixes. Re-run the targeted failing scenarios before completing this step." --assignment "$ASSIGNMENT_TARGET"
+```
 
 #### Option C: Ask the User
 
@@ -542,10 +800,33 @@ If uncertain, ask the user whether to retry, add a fix step, or abort.
 ### 8. Repeat
 
 Check status again:
+
 - If there is a next step, continue the loop from step 1
 - If all steps are `done`, proceed to Completion
 - If assignment has failed steps and no fix is planned, report to user
 
+### 9. Pre-Exit Verification (Required)
+
+Before ending the drive session with a final user-facing response, re-run:
+
+```bash
+FINAL_STATUS=$(ace-assign status --assignment "$ASSIGNMENT_TARGET" --format json)
+echo "$FINAL_STATUS"
+```
+
+Required checks:
+
+- If any steps remain `pending` or `active` and no explicit blocker was recorded, resume the loop instead of stopping.
+- If the assignment is `paused`, `active_steps` is empty, and `next_step` is present, run:
+
+  ```bash
+  ace-assign start --assignment "$ASSIGNMENT_TARGET"
+  ```
+
+  then continue the loop.
+
+- Only produce a final completion response when the assignment is actually complete or when this workflow has already reached a documented blocker/failure stop condition.
+
 ## Completion
 
 When `ace-assign status` shows all steps as `done`:
@@ -555,6 +836,7 @@ ace-assign status --assignment "$ASSIGNMENT_TARGET"
 ```
 
 Example output:
+
 ```
 Assignment: work-on-task-123 (8or5kx)
 
@@ -567,6 +849,7 @@ All steps complete!
 ```
 
 Summarize the assignment results to the user:
+
 - What was accomplished
 - Any artifacts created (PRs, commits, etc.)
 - Next steps or follow-up actions
@@ -604,6 +887,7 @@ When executing a step with a `skill:` field:
 |----------|--------|
 | No active assignment | Create an assignment first via `/as-assign-create` |
 | All steps done | Report completion to user |
+| Assignment paused with pending work | Run `ace-assign start --assignment "$ASSIGNMENT_TARGET"` and continue driving |
 | Step fails | Attempt first, then use `fail` with command/error evidence; decide retry/add/ask |
 | Skill not found | Execute instructions directly without skill |
 | Unclear instructions | Ask user for clarification |
@@ -616,7 +900,7 @@ When executing a step with a `skill:` field:
 | Status | Meaning | Next Action |
 |--------|---------|-------------|
 | `pending` | Step not started | Cannot execute (wait for queue) |
-| `in_progress` | Step is active | Execute this step |
+| `active` | Step is active | Execute this step |
 | `done` | Step completed | Move to next step |
 | `failed` | Step failed | Decide: retry, add fix, or abort |
 
@@ -630,11 +914,11 @@ When executing a step with a `skill:` field:
 │   ├── assignment.yaml           # Assignment metadata
 │   ├── steps/                   # Step files (.st.md extension)
 │   │   ├── 010-init.st.md       # done
-│   │   ├── 020-implement.st.md  # in_progress
+│   │   ├── 020-implement.st.md  # active
 │   │   └── 030-test.st.md       # pending
 │   └── reports/                  # Report files (.r.md extension)
 │       ├── 010-init.r.md        # completed report
-│       └── 020-implement.r.md   # in-progress report
+│       └── 020-implement.r.md   # active-step report
 └── def456/
     ├── assignment.yaml
     ├── steps/
@@ -642,6 +926,7 @@ When executing a step with a `skill:` field:
 ```
 
 Each step has:
+
 - **Step file** (`steps/NNN-name.st.md`) - Contains step instructions and status
 - **Report file** (`reports/NNN-name.r.md`) - Contains completion report (created when step is done)
 
@@ -680,28 +965,33 @@ $ ASSIGNMENT_TARGET=8or5kx
 
 # 1. Check status
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
-Step 010: onboard [in_progress]
+Next: 010 onboard
+
+# 2. Start the next pending step
+$ ace-assign start --assignment "$ASSIGNMENT_TARGET"
+[Step 010 becomes active]
 
-# 2. Execute step (has skill: onboard)
+# 3. Execute step (has skill: onboard)
 $ /as-onboard
 [Onboarding workflow runs...]
 
-# 3. Write report
+# 4. Write report
 $ ace-assign finish --message onboard-complete.md --assignment "$ASSIGNMENT_TARGET"
-Step 010 marked done, advancing to 020
+[Step 010 marked done]
 
-# 4. Check status again
+# 5. Check status again
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
-Step 020: work-on-task [in_progress]
+Next: 020 work-on-task
 
-# 5. Execute next step (has skill: as-task-work)
+# 6. Start and execute next step (has skill: as-task-work)
+$ ace-assign start --assignment "$ASSIGNMENT_TARGET"
 $ /as-task-work 148
 [Task workflow runs...]
 
-# 6. Report and continue...
+# 7. Report and continue...
 $ ace-assign finish --message task-done.md --assignment "$ASSIGNMENT_TARGET"
 
-# 7. Eventually...
+# 8. Eventually...
 $ ace-assign status --assignment "$ASSIGNMENT_TARGET"
 All steps complete!
 ```