ace-assign 0.41.10 → 0.53.4

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

@@ -0,0 +1,32 @@
+{
+  "backend": "asciinema",
+  "tape_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.tape.yml",
+  "cast_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.cast",
+  "visual_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.gif",
+  "sandbox_path": "/home/mc/ace-t.u53.0/.ace-local/demo/sandbox/8rekyn",
+  "verification": {
+    "status": "scenario-defect",
+    "classification": "scenario_defect",
+    "summary": "Recording scenario failed verification",
+    "retryable": true,
+    "report_path": "/home/mc/ace-t.u53.0/.ace-local/demo/fork-provider-error-report.md",
+    "details": {
+      "cast_path": "/home/mc/ace-t.u53.0/ace-assign/docs/demo/fork-provider.cast",
+      "inputs_recorded": 0,
+      "echoed_commands_recorded": 70,
+      "script_commands_recorded": 0,
+      "commands_expected": 7,
+      "captured_vars": {
+        "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"
+      },
+      "missing_vars": [],
+      "missing_output": [
+        "{\"Task context\" => nil}"
+      ],
+      "missing_output_sequence": null,
+      "forbidden_hits": [],
+      "assertion_failures": [],
+      "assertions_skipped": false
+    }
+  }
+}

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

@@ -1,34 +1,79 @@
 ---
-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"
+- run: |
+    bash -lc 'sleep 45; tmux detach-client -s fork-demo || true' >/tmp/ace-demo-fork-provider-detach.log 2>&1 &
 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
+  - type: tmux attach -t fork-demo
+    sleep: 2s
+  - 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
+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

@@ -1,10 +1,11 @@
 ---
 doc-type: user
 title: ace-assign Usage Guide
-purpose: Complete command reference for ace-assign queue orchestration, hierarchy, and fork execution.
+purpose: Complete command reference for ace-assign queue orchestration, hierarchy,
+  and fork execution.
 ace-docs:
-  last-updated: 2026-03-26
-  last-checked: 2026-03-26
+  last-updated: '2026-04-01'
+  last-checked: '2026-04-01'
 ---
 
 # ace-assign Usage Guide
@@ -22,12 +23,31 @@ 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 step
 ace-assign finish --message step-010.md
 ace-assign status
 ```
@@ -86,12 +106,41 @@ 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
+
+HITL stall behavior:
+
+- Canonical contract lives in `wfi://hitl` (`ace-hitl` package workflow).
+- If a step is failed with canonical message format `HITL: <id> <path>`, `ace-assign status` prints operator guidance with the matching `ace-hitl show <id>` command and available path hint.
+- Recommended resume flow:
+  - `ace-hitl show <id>`
+  - requester path (default): `ace-hitl wait <id>`
+  - fallback path (when waiter inactive): `ace-hitl update <id> --answer "<decision>" --resume`
+  - `ace-assign retry <failed-step> --assignment <assignment-id>`
+- 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 current in-progress step, the next workable step, 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.
@@ -105,6 +154,10 @@ Options:
 ### `ace-assign finish [STEP] --message VALUE`
 
 Complete current in-progress step (or explicit step in 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
+current in-progress step in that target.
 
 `--message` accepts:
 
@@ -168,9 +221,16 @@ Options:
 - `--provider <provider:model>`
 - `--cli-args <args>`
 - `--timeout <seconds>`
+- `--launch-mode auto|headless|tmux`
 - `--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 `<current-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
+
 Provider resolution precedence for fork execution:
 
 1. CLI `--provider`

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

@@ -95,7 +95,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 +105,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

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-07
 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 `in_progress` 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