ace-assign 0.42.4 → 0.55.0

data/docs/demo/fork-provider.recording.json

@@ -0,0 +1,30 @@
+{
+  "backend": "asciinema",
+  "tape_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.tape.yml",
+  "cast_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.cast",
+  "visual_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.gif",
+  "sandbox_path": "/home/mc/ace-t.n1d/.ace-local/demo/sandbox/8rfe9v",
+  "verification": {
+    "status": "pass",
+    "classification": "pass",
+    "summary": "Verification passed",
+    "retryable": false,
+    "report_path": null,
+    "details": {
+      "cast_path": "/home/mc/ace-t.n1d/ace-assign/docs/demo/fork-provider.cast",
+      "inputs_recorded": 0,
+      "echoed_commands_recorded": 435,
+      "script_commands_recorded": 0,
+      "commands_expected": 3,
+      "captured_vars": {
+        "ACE_TMUX_SESSION": "fork-demo PROJECT_ROOT_PATH=\"$PWD\" ace-assign status --assignment \"$(cat ASSIGN_ID)@010\""
+      },
+      "missing_vars": [],
+      "missing_output": [],
+      "missing_output_sequence": [],
+      "forbidden_hits": [],
+      "assertion_failures": [],
+      "assertions_skipped": false
+    }
+  }
+}

data/docs/demo/fork-provider.tape.yml

@@ -1,34 +1,91 @@
 ---
-description: Show per-step fork provider — different steps run with different LLM models
+description: Show tmux-backed fork execution opening a fork staging window from the current work window
 tags:
 - ace-assign
 - fork
-- provider
+- tmux
+- demo
 settings:
-  font_size: 16
-  width: 1000
-  height: 500
+  backend: asciinema
+  font_size: 14
+  width: 1200
+  height: 720
   format: gif
+  output: ace-assign/docs/demo/fork-provider.gif
 setup:
 - sandbox
 - git-init
-- copy-fixtures
+- run: |
+    ruby -e 'require "fileutils"; root = File.dirname(ENV.fetch("BUNDLE_GEMFILE")); FileUtils.mkdir_p(".ace"); FileUtils.cp_r(File.join(root, ".ace", "llm"), File.join(".ace", "llm")); {".codex" => "skills", ".claude" => "skills", ".pi" => "skills"}.each { |dir, sub| src = File.join(root, dir, sub); next unless Dir.exist?(src); FileUtils.mkdir_p(dir); FileUtils.cp_r(src, File.join(dir, sub)) }'
+- run: |
+    cat > fork-demo-job.yaml <<'YAML'
+    assignment:
+      name: tmux-fork-demo
+      description: Minimal assignment to demo tmux-backed fork execution
+    steps:
+      - name: demo-root
+        context: fork
+        instructions: |
+          Demonstrate tmux-backed fork execution for the assignment subtree.
+        sub_steps:
+          - onboard
+    YAML
+- run: |
+    PROJECT_ROOT_PATH="$PWD" ace-assign create --yaml fork-demo-job.yaml
+    ruby -e 'link = ".ace-local/assign/.latest"; abort "no latest assignment" unless File.symlink?(link); File.write("ASSIGN_ID", File.basename(File.readlink(link)))'
+- run: tmux new-session -d -s fork-demo -n work -c "$PWD" "bash --noprofile --norc -i"
 scenes:
-- name: Show step frontmatter with fork.provider
+- name: Attach to the operator work window
   commands:
-  - type: "cat .ace-local/assign/demoXx/steps/020-implement.st.md"
-    sleep: 4s
-- name: Status shows per-step Fork Provider
+  - tmux:
+      action: attach
+      session: fork-demo
+  - tmux:
+      action: wait
+      for: window-active
+      session: fork-demo
+      window: work
+  - type: tmux display-message -p '#W'
+    sleep: 2s
+- name: Launch the fork into a visible tmux window
   commands:
-  - type: clear
-    sleep: 1s
-  - type: "ace-assign status"
-    sleep: 4s
-- name: fork-run resolves step provider
-  commands:
-  - type: clear
-    sleep: 1s
-  - type: "ace-assign fork-run --root 020 --dry-run"
-    sleep: 4s
+  - type: ACE_TMUX_SESSION=fork-demo PROJECT_ROOT_PATH="$PWD" ace-assign status --assignment "$(cat ASSIGN_ID)@010"
+    sleep: 2s
+  - type: bash -lc 'ACE_TMUX_SESSION=fork-demo PROJECT_ROOT_PATH="$PWD" ace-assign fork-run --assignment "$(cat ASSIGN_ID)@010" --launch-mode tmux --provider codex:gpt@yolo --cli-args "--no-alt-screen" --timeout 120 &'
+    sleep: 35s
+  - tmux:
+      action: wait
+      for: window-exists
+      session: fork-demo
+      window: work-fs
+  - tmux:
+      action: detach
+      session: fork-demo
+verify:
+  require_output:
+  - work
+  - work-fs
+  - $as-assign-drive
+  - Explored
+  require_output_sequence:
+  - work
+  - ace-assign fork-run
+  - work-fs
+  - $as-assign-drive
+  - Explored
+  forbid_output:
+  - requires an active tmux session
+  - Could not resolve current tmux window
+  - No such file or directory
+  - Unknown provider
+  - Unknown providers in llm.providers.active
+  - Fork session execution failed
+  - does not support interactive mode
+  - Do you trust the contents of this directory?
+  assert_commands:
+  - 'ASSIGN_ID=$(cat ASSIGN_ID); test -f ".ace-local/assign/${ASSIGN_ID}/sessions/010-session.yml"'
+  - |
+    ASSIGN_ID=$(cat ASSIGN_ID); ruby -e 'require "yaml"; id = File.read("ASSIGN_ID").strip; data = YAML.safe_load_file(".ace-local/assign/#{id}/sessions/010-session.yml"); abort "bad metadata" unless data["launch_mode"] == "tmux" && data["tmux_window"] == "work-fs" && data["provider"] == "codex" && data["model"] == "gpt-5.4"'
 teardown:
+- run: tmux kill-session -t fork-demo || true
 - cleanup

data/docs/getting-started.md

@@ -67,6 +67,7 @@ ace-assign create --task t.100,t.101 --preset work-on-task
 
 ```bash
 ace-assign status
+ace-assign step
 ace-assign finish --message onboard.md
 ace-assign status
 ```
@@ -97,7 +98,8 @@ Use status views:
 
 ```bash
 ace-assign status
-ace-assign status --flat
+ace-assign status --mode full
+ace-assign status --mode progress
 ```
 
 ## 5) Use scoped assignment targeting
@@ -116,7 +118,8 @@ ace-assign finish --message report.md --assignment abc123@010.01
 |---------|---------|
 | `ace-assign create --yaml job.yaml` | Create assignment from YAML |
 | `ace-assign create --task t.xyz` | Create assignment from task refs |
-| `ace-assign status` | Show current queue |
+| `ace-assign status` | Show current queue summary |
+| `ace-assign step` | Show current or next step instructions |
 | `ace-assign start` | Start next workable step |
 | `ace-assign finish --message done.md` | Complete in-progress step |
 | `ace-assign fail --message "error"` | Mark current step failed |

data/docs/usage.md

@@ -4,8 +4,8 @@ title: ace-assign Usage Guide
 purpose: Complete command reference for ace-assign queue orchestration, hierarchy,
   and fork execution.
 ace-docs:
-  last-updated: '2026-04-01'
-  last-checked: '2026-04-01'
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # ace-assign Usage Guide
@@ -23,12 +23,32 @@ Recommended:
 ace-assign finish --message report.md
 ```
 
+## Testing Contract
+
+Use package-scoped test commands with explicit layers:
+
+```bash
+ace-test ace-assign
+ace-test ace-assign feat
+ace-test ace-assign all
+ace-test-e2e ace-assign
+```
+
+For assignment verification, `verify-test-suite` is the standard gate:
+
+```bash
+ace-test <package> all --profile 6
+ace-test-suite --target all
+```
+
 ## Core Lifecycle
 
 
 ```bash
 ace-assign create --yaml job.yaml
 ace-assign status
+ace-assign start
+ace-assign step
 ace-assign finish --message step-010.md
 ace-assign status
 ```
@@ -38,6 +58,7 @@ Use scoped targeting when needed:
 
 ```bash
 ace-assign status --assignment abc123@010.01
+ace-assign start --assignment abc123@010.01
 ace-assign finish --message done.md --assignment abc123@010.01
 ```
 
@@ -87,12 +108,20 @@ Show queue status for active or explicitly targeted assignment.
 Options:
 
 - `--flat, -f`
+- `--mode compact|progress|full`
 - `--format table|json`
 - `--assignment <id>`
 - `--all, -a`
 - `--quiet, -q`
 - `--debug, -d`
 
+Text modes:
+
+- `compact` (default) prints a short summary, hidden-step stats, and up to 5 upcoming step lines
+- `progress` prints a single summary line
+- `full` prints the full tree/table without step instructions
+- JSON emits `active_steps` for all active steps in scope and `next_step` only when no step is active in that scope
+
 HITL stall behavior:
 
 - Canonical contract lives in `wfi://hitl` (`ace-hitl` package workflow).
@@ -105,9 +134,19 @@ HITL stall behavior:
 - Completion-attention flow:
   - When assignment work is complete but explicit user action is needed, create an approval HITL event (`kind=approval`) and include the resume instruction for `/as-assign-drive <assignment-id>`.
 
+### `ace-assign step [STEP]`
+
+Show instructions for the deepest active step in scope, the next workable pending step when nothing is active, or an explicit step number.
+
+Options:
+
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
 ### `ace-assign start [STEP]`
 
-Start next workable pending step, or an explicit pending step in the active assignment.
+Mark the next workable pending step active, or mark an explicit pending step active in the targeted assignment or subtree.
 
 Options:
 
@@ -117,7 +156,11 @@ Options:
 
 ### `ace-assign finish [STEP] --message VALUE`
 
-Complete current in-progress step (or explicit step in active assignment) with report content.
+Complete the current active step (or explicit active step in the active assignment) with report content.
+Use positional `STEP` only for the active assignment. When targeting another
+assignment or a scoped subtree, pass `--assignment <id>` or
+`--assignment <id@step>` without a positional `STEP`; the command finishes the
+deepest active step in that target.
 
 `--message` accepts:
 
@@ -181,9 +224,35 @@ Options:
 - `--provider <provider:model>`
 - `--cli-args <args>`
 - `--timeout <seconds>`
+- `--launch-mode auto|headless|tmux`
+- `--callback`
 - `--quiet, -q`
 - `--debug, -d`
 
+Launch modes:
+
+- `auto` (default): use tmux when the current process is already inside tmux or `ACE_TMUX_SESSION` is set; otherwise use the headless subprocess path
+- `headless`: force the existing provider subprocess path and never create tmux panes
+- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically. The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`. Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
+- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+  - This mode consumes the shared `ace-tmux` runtime/control surface for tmux targeting, pane dispatch, and diagnostics.
+  - The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`.
+  - Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
+  - Assignment step state remains the source of truth for subtree completion or failure; pane capture is diagnostic support only.
+
+Callback mode:
+
+- `--callback`: tmux-only fork mode that captures the pane where `fork-run` was started and passes it into the child fork session as `ACE_ASSIGN_CALLBACK_PANE`
+- In callback mode the child agent is instructed to send one final status sentence back to the origin pane with `ace-tmux send` before stopping
+- Callback mode is intended for interactive parent/child agent tmux flows where the parent stays idle until the child sends the final message back
+
+Launch-mode precedence for fork execution:
+
+1. CLI `--launch-mode`
+2. Step frontmatter `fork.mode`
+3. Config `execution.launch_mode`
+4. Built-in default `auto`
+
 Provider resolution precedence for fork execution:
 
 1. CLI `--provider`
@@ -200,6 +269,7 @@ status: pending
 context: fork
 fork:
   provider: "claude:sonnet@yolo"
+  mode: "tmux"
 ---
 ```
 

data/handbook/guides/fork-context.g.md

@@ -1,10 +1,11 @@
 ---
 doc-type: guide
 title: Fork Context Guide
-purpose: Explain fork context execution model, boundaries, and recovery patterns for ace-assign subtree delegation.
+purpose: Explain fork context execution model, boundaries, and recovery patterns for
+  ace-assign subtree delegation.
 ace-docs:
-  last-updated: 2026-03-18
-  last-checked: 2026-03-21
+  last-updated: '2026-04-23'
+  last-checked: '2026-04-23'
 ---
 
 # Fork Context Guide
@@ -13,13 +14,14 @@ ace-docs:
 
 Fork context enables step files to run in isolated agent contexts using the Task tool. When a step has `context: fork` in its frontmatter, ace-assign outputs instructions for the orchestrating agent to execute the step via a subagent.
 
-You can also set a per-step provider override with `fork.provider`:
+You can also set per-step launch overrides with `fork.provider` and `fork.mode`:
 
 ```yaml
 ---
 context: fork
 fork:
   provider: "claude:sonnet@yolo"
+  mode: "tmux"
 ---
 ```
 
@@ -30,6 +32,13 @@ Provider precedence during `ace-assign fork-run`:
 3. Assign config `execution.provider`
 4. Built-in default
 
+Launch-mode precedence during `ace-assign fork-run`:
+
+1. CLI `--launch-mode`
+2. Step `fork.mode`
+3. Assign config `execution.launch_mode`
+4. Built-in default `auto`
+
 For hierarchical split workflows, use **parent-only** fork markers:
 - Split parent step: `context: fork`
 - Child steps (`onboard-base`, `task-load`, `plan-task`, `work-on-task`, `verify-test`, `release-minor`): no `context: fork`
@@ -95,7 +104,7 @@ Return structured summary:
 When `ace:assign-drive` (or manual orchestration) encounters a fork-enabled subtree:
 
 1. Runs `ace-assign status`
-2. Detects `Fork subtree detected (root: ...)` in output (outside fork scope)
+2. Uses compact/full status only to identify the active fork-capable step or subtree root
 3. Delegates with `ace-assign fork-run --assignment <id>@<root>`
 4. Fork launcher executes `/as-assign-drive <id>@<root>` in a scoped process
 5. Scoped process advances only inside subtree
@@ -105,7 +114,7 @@ When `ace:assign-drive` (or manual orchestration) encounters a fork-enabled subt
 ace:assign-drive loop
   |
   +-- ace-assign status
-  +-- Detects "Fork subtree detected (root: ...)"
+  +-- Resolve fork subtree root from assignment state
   +-- ace-assign fork-run --assignment <id>@<root>
   +-- Forked /as-assign-drive <id>@<root>
   +-- Subtree completes
@@ -127,6 +136,21 @@ The orchestrating agent:
 - Processes subagent reports
 - Handles failures and retries
 
+## Scoped Status Semantics
+
+Fork execution uses two layers of active ownership:
+
+- The fork root stays `active` while the delegated session owns that subtree.
+- Inside that subtree, zero or one deepest started descendant may also be `active`.
+
+Status reporting is scope-aware:
+
+- Unscoped status lists all `active_steps` in queue order and hides pending descendants under an active fork root from global `next_step` selection.
+- Scoped status (`--assignment <id>@<root>`) reports activity only inside that subtree.
+- When nothing is active inside the current scope, status reports `next_step` instead of predicting started work.
+
+This keeps queue eligibility separate from execution state: pending descendants stay pending until scoped execution explicitly starts them.
+
 ## Recovery From Failed Fork Subtrees
 
 When a forked subtree fails, use **adaptive minimal-safe replay**:
@@ -245,4 +269,4 @@ ACE_DEBUG=1 ace-assign status
 
 - [ace-assign README](../../README.md) - Main documentation
 - [Work Queue Model](../workflow-instructions/drive-assignment.wf.md) - Assignment management
-- `ace-assign fork-run --root <step> --assignment <id>` - Prepare subtree-scoped fork session
+- `ace-assign fork-run --root <step> --assignment <id>` - Prepare subtree-scoped fork session

data/handbook/skills/as-assign-drive/SKILL.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
   - Skill
 argument-hint: "[assignment[@scope]]"
-last_modified: 2026-02-11
+last_modified: 2026-04-23
 source: ace-assign
 skill:
   kind: workflow
@@ -22,3 +22,15 @@ skill:
 ---
 
 Load and run `ace-bundle wfi://assign/drive` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.
+
+Hard stop rule:
+
+- Do not stop after intermediate progress.
+- Do not stop while waiting on a forked subtree; keep polling and resume the parent drive loop as soon as the subtree reaches a terminal state.
+- Treat `ace-assign status --assignment <id>@<root>` as the source of truth for fork completion; quiet terminal output is not enough reason to stop or declare a stall.
+- If a prior terminal or drive session ended, re-enter from assignment state and continue from the next runnable work instead of depending on the old terminal handle.
+- Before any final response, re-check pinned assignment status. If any runnable `pending` or `active` work remains, continue driving.
+- If unrelated dirty files are generated side effects outside task scope, clean/reset them instead of auto-committing them.
+- Use progress updates for partial status only.
+- Return a final user-facing completion response only when the assignment is complete or the workflow reaches an explicit blocker/failure stop condition.
+- If pending work remains runnable, continue driving.

data/handbook/skills/as-create-retro-internal/SKILL.md

@@ -0,0 +1,29 @@
+# bundle: wfi://assign/create-retro-internal
+# agent: general-purpose
+---
+name: as-create-retro-internal
+description: Internal helper for retrospective creation in assignment closeout
+user-invocable: false
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-retro:*)
+  - Read
+  - Write
+argument-hint: "[retro-title]"
+last_modified: 2026-04-05
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/create-retro-internal
+assign:
+  source: wfi://assign/create-retro-internal
+  steps:
+    - name: create-retro
+      description: Create retrospective summarizing outcomes and lessons
+      prerequisites:
+        - name: reflect-and-refactor
+          strength: recommended
+---
+
+Load and run `ace-bundle wfi://assign/create-retro-internal` in the current project, then follow the loaded workflow as the source of truth.

data/handbook/skills/as-mark-task-done-internal/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: as-mark-task-done-internal
+description: Internal helper for marking tasks done with verification
+# bundle: wfi://assign/mark-task-done-internal
+# agent: general-purpose
+user-invocable: false
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-task:*)
+  - Read
+  - Write
+argument-hint: "[taskref]"
+last_modified: 2026-04-05
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/mark-task-done-internal
+assign:
+  source: wfi://assign/mark-task-done-internal
+  steps:
+    - name: mark-task-done
+      description: Mark task complete and verify persisted status
+      prerequisites:
+        - name: work-on-task
+          strength: required
+---
+
+Load and run `ace-bundle wfi://assign/mark-task-done-internal` in the current project, then follow the loaded workflow as the source of truth.

data/handbook/skills/as-reflect-and-refactor-internal/SKILL.md

@@ -0,0 +1,30 @@
+# bundle: wfi://assign/reflect-and-refactor-internal
+# agent: general-purpose
+---
+name: as-reflect-and-refactor-internal
+description: Internal helper for architecture reflection and bounded refactoring
+user-invocable: false
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-review:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+argument-hint: "[assignment-context]"
+last_modified: 2026-04-05
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/reflect-and-refactor-internal
+assign:
+  source: wfi://assign/reflect-and-refactor-internal
+  steps:
+    - name: reflect-and-refactor
+      description: Run architecture reflection and execute bounded refactoring
+      prerequisites:
+        - name: work-on-task
+          strength: required
+---
+
+Load and run `ace-bundle wfi://assign/reflect-and-refactor-internal` in the current project, then follow the loaded workflow as the source of truth.

data/handbook/skills/as-task-load-internal/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: as-task-load-internal
+description: Internal helper for loading task context into assignment execution
+# bundle: wfi://assign/task-load-internal
+# agent: general-purpose
+user-invocable: false
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+argument-hint: "[taskref]"
+last_modified: 2026-04-05
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/task-load-internal
+assign:
+  source: wfi://assign/task-load-internal
+  steps:
+    - name: task-load
+      description: Load task behavioral spec and dependency context into assignment execution
+      prerequisites:
+        - name: onboard-base
+          strength: recommended
+---
+
+Load and run `ace-bundle wfi://assign/task-load-internal` in the current project, then follow the loaded workflow as the source of truth.

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

@@ -172,14 +172,14 @@ session:
 
 steps:
   - name: verify-test-suite
-    workflow: wfi://test/verify-suite
+    source: wfi://assign/verify-test-suite
     instructions:
       - Run package test verification.
 ```
 
 Step mapping source of truth:
 - `name` from canonicalized step catalog entry
-- `workflow` from canonicalized step catalog entry
+- `source` from canonicalized step catalog entry (step runtime contract)
 - `context` from canonicalized step catalog entry (if set)
 - `instructions` as assignment overlay from catalog description + request-specific context
 
@@ -253,4 +253,4 @@ After job.yaml is created:
 /as-assign-create <job.yaml>
 # or
 /as-assign-create "...intent..." --run
-```
+```

data/handbook/workflow-instructions/assign/create-retro-internal.wf.md

@@ -0,0 +1,11 @@
+# create-retro-internal
+
+## Purpose
+
+Capture retrospective learnings after assignment implementation/release steps complete.
+
+## Steps
+
+1. Summarize outcomes, key decisions, and verification results.
+2. Capture issues, risks, and follow-up actions.
+3. Record the retrospective artifact in the task/retro system used by the assignment.

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

@@ -3,7 +3,7 @@ doc-type: workflow
 title: Create Assignment Workflow
 purpose: workflow instruction for smart public create UX that renders hidden specs and calls deterministic ace-assign create
 ace-docs:
-  last-updated: 2026-03-18
+  last-updated: 2026-04-07
   last-checked: 2026-03-21
 ---
 
@@ -128,12 +128,12 @@ session:
 
 steps:
   - name: <step-name>
-    workflow: <workflow-ref-if-public-step>
+    source: <source-ref-skill-or-wfi>
     instructions:
       - <instruction line>
 ```
 
-`instructions` are assignment overlay only. The reusable execution body comes from the referenced workflow during `ace-assign create`.
+`instructions` are assignment overlay only. The reusable execution body comes from the canonical source resolution during `ace-assign create`.
 
 Rules:
 - Each invocation writes a new file (no in-place mutation of prior hidden specs).
@@ -156,6 +156,8 @@ If `--run` is present, hand off to drive as the last step:
 /as-assign-drive <assignment-id>
 ```
 
+`/as-assign-drive` is a run-until-complete-or-blocked handoff, not a one-step progress check. Once handed off, it should keep driving until the assignment is actually complete or reaches an explicit blocker/failure stop condition.
+
 If no workable step exists, keep creation successful and report why drive cannot continue.
 
 ### 7. Report Result
@@ -203,6 +205,7 @@ Step 010: ...
 - Capability skills remain excluded from assign composition
 - Skill-backed steps still expand through runtime `assign.source` metadata
 - `--run` (when requested) triggers drive handoff as the final workflow step
+- Drive handoff semantics are run-until-complete-or-blocked, not stop-after-first-progress
 
 ## Verification