ace-assign 0.42.4 → 0.53.4

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

@@ -1,9 +1,18 @@
 ---
+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-updated: 2026-04-12
   last-checked: 2026-03-21
 ---
 
@@ -104,12 +113,55 @@ 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 the same assignment 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.
+- 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 `in_progress` 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
+- useful progress was made
+- a prior terminal session ended
+- the parent assignment auto-advanced to the next active step
+
+Concrete example:
+
+- `010.01 done` and `010.02.01 in_progress` means continue driving the assignment. It is not a completion boundary.
+
 ### 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 +171,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 +214,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
+- 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 +252,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 init` 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 +276,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 +285,7 @@ NUMBER       STATUS       NAME                           FORK   CHILDREN
 ```
 
 Step 020 shows `FORK: yes` → run:
+
 ```bash
 ace-assign fork-run --assignment <id>@020
 ```
@@ -209,7 +293,7 @@ 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 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>`.
 - If the current step is a top-level step with `FORK: yes` and no matching scope is active, delegate immediately.
 
 #### Nested Batch Containers (Container → Fork Children)
@@ -222,10 +306,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 +322,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 +350,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).
@@ -292,13 +387,64 @@ 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.
+
+- 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."
+
+#### 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 `in_progress` 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).
+
+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 +453,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 +497,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.
@@ -358,11 +510,32 @@ 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:
+
 ```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 +601,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 +624,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 +687,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
@@ -535,6 +719,12 @@ ace-assign add "fix-issue" --instructions "Fix the failing tests and verify" --a
 
 New step is inserted after the current in-progress 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
 
 If uncertain, ask the user whether to retry, add a fix step, or abort.
@@ -542,10 +732,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 `in_progress` and no explicit blocker was recorded, resume the loop instead of stopping.
+- If the assignment is `paused`, `current_step` is `null`, and pending steps remain, 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 +768,7 @@ ace-assign status --assignment "$ASSIGNMENT_TARGET"
 ```
 
 Example output:
+
 ```
 Assignment: work-on-task-123 (8or5kx)
 
@@ -567,6 +781,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 +819,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 |
@@ -642,6 +858,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)
 

data/handbook/workflow-instructions/assign/mark-task-done-internal.wf.md

@@ -0,0 +1,12 @@
+# mark-task-done-internal
+
+## Purpose
+
+Mark a task as done and verify the state transition persisted.
+
+## Steps
+
+1. Run `ace-task update <taskref> --set status=done --move-to archive --git-commit`.
+2. Verify with `ace-task show <taskref>` and confirm `status: done`.
+3. If the task has a parent, check whether siblings are all done; when true, mark the parent done and verify.
+4. Repeat upward only while all siblings remain done.

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

@@ -336,7 +336,7 @@ session:
 
 steps:
   - name: <step-name>
-    skill: <skill-reference>  # If present in preset
+    source: <source-reference>  # Canonical: skill://... or wfi://...
     instructions:
       - <resolved instruction line>
   # ... more steps
@@ -344,7 +344,7 @@ steps:
 
 ### 8. Output Result
 
-Default output: `<task>/jobs/<timestamp>-job.yml` (e.g., `.ace-taskflow/v.0.9.0/tasks/229-xxx/jobs/k5abc123-job.yml`)
+Default output: `<task>/jobs/<timestamp>-job.yml` (e.g., `.ace-task/v.0.9.0/tasks/229-xxx/jobs/k5abc123-job.yml`)
 
 Custom output: Use `--output path/to/custom.yaml`
 
@@ -379,19 +379,19 @@ session:
 
 steps:
   - name: onboard
-    skill: as-onboard
+    source: skill://as-onboard
     instructions:
       - Onboard yourself to the codebase.
       - Load context and understand the project structure.
 
   - name: work-on-task
-    skill: as-task-work
+    source: skill://as-task-work
     instructions:
       - Work on task 123.
       - Implement the required changes following project conventions.
 
   - name: create-pr
-    skill: as-github-pr-create
+    source: skill://as-github-pr-create
     instructions:
       - Create a pull request for the changes.
       - Capture the PR number for subsequent review steps.

data/handbook/workflow-instructions/assign/reflect-and-refactor-internal.wf.md

@@ -0,0 +1,14 @@
+# reflect-and-refactor-internal
+
+## Purpose
+
+Run architecture reflection and bounded refactoring before release/closeout.
+
+## Steps
+
+1. Validate implementation/demo state.
+2. Run architecture-focused review on the active diff.
+3. Categorize findings (refactor/accept/skip).
+4. Execute bounded refactoring for selected findings only.
+5. Commit refactor changes separately.
+6. If a replan trigger is hit, inject follow-up implementation steps and rerun once.

data/handbook/workflow-instructions/assign/run-in-batches.wf.md

@@ -3,7 +3,7 @@ doc-type: workflow
 title: Run In Batches Workflow
 purpose: workflow instruction for reusable repeated-item orchestration with deterministic assignment creation
 ace-docs:
-  last-updated: 2026-03-18
+  last-updated: 2026-04-07
   last-checked: 2026-03-21
 ---
 
@@ -163,6 +163,8 @@ If `--run` is present:
 /as-assign-drive <assignment-id>
 ```
 
+This handoff must continue through the full batch execution, including all child fork subtrees, until the assignment is complete or an explicit blocker/failure stop condition is reached. Child completion is not a valid stop boundary.
+
 If no workable step is available, keep creation successful and report why drive did not continue.
 
 ### 7. Report Result
@@ -203,6 +205,7 @@ Show:
 - Parent/child metadata reflects scheduler intent (`parallel`, `max_parallel`, `fork_retry_limit`)
 - `{{item}}` substitution and `Target item:` fallback are deterministic
 - Optional `--run` handoff delegates to `/as-assign-drive`
+- Optional `--run` handoff preserves drive's run-until-complete-or-blocked semantics across the whole batch
 
 ## Verification
 

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

@@ -3,7 +3,7 @@ doc-type: workflow
 title: Start Assignment Workflow (Legacy Compatibility)
 purpose: preserve compatibility for as-assign-start while routing to public assign/create + assign/drive flow
 ace-docs:
-  last-updated: 2026-03-18
+  last-updated: 2026-04-07
   last-checked: 2026-03-21
 ---
 
@@ -39,8 +39,11 @@ Primary public UX remains:
 /as-assign-drive <assignment-id>
 ```
 
+When this handoff occurs, `/as-assign-drive` must continue until the assignment is complete or explicitly blocked. It is not a single-step progress probe.
+
 ## Success Criteria
 
 - Preserves compatibility entrypoint for orchestration examples.
 - Delegates behavior to `assign/create` and `assign/drive`.
-- Does not redefine the public assignment flow.
+- Does not redefine the public assignment flow.
+- Preserves drive's run-until-complete-or-blocked semantics.

data/handbook/workflow-instructions/assign/task-load-internal.wf.md

@@ -0,0 +1,12 @@
+# task-load-internal
+
+## Purpose
+
+Load task behavioral specification and dependency context for assignment execution.
+
+## Steps
+
+1. Run `ace-bundle task://<taskref>` for the target task reference.
+2. If task dependencies are declared, run `ace-bundle task://<dep-ref>` for each dependency.
+3. Review relevant dependency reports under `.ace-local/assign/` so the plan/work steps build on prior implementation.
+4. Confirm context is loaded before proceeding.