ace-assign 0.37.0

data/README.md

@@ -0,0 +1,87 @@
+<div align="center">
+  <h1> ACE - Assign </h1>
+
+  Multi-step assignment execution with nesting, fork delegation, and inspectable traces.
+
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.S.png" alt="ACE Logo" width="480">
+
+  <a href="https://rubygems.org/gems/ace-assign"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-assign.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+`ace-assign` turns work into a multi-step assignment with nested substeps, fork delegation to long-running agent subprocesses, and inspectable session traces. Steps are defined from a [step catalog](.ace-defaults/assign/catalog/steps/) and assembled via [presets](.ace-defaults/assign/presets/work-on-task.yml) or composed manually. Each step can reference a [workflow instruction](../ace-task/handbook/workflow-instructions/task/work.wf.md) for execution details. Assignments are restartable -- failed steps keep their lineage so you can retry or inject fixes without losing history.
+```
+
+❯ ace-assign status
+QUEUE - Assignment: work-on-task-8qm.t.5nx-job.yml (8qm5rt)
+
+NUMBER       STATUS       NAME                           FORK   CHILDREN
+------------------------------------------------------------------------------
+000          ✓ Done       onboard
+010          ✓ Done       batch-tasks                           (28/28 done)
+|-- 010.01   ✓ Done       work-on-8qm.t.5nx.0            yes    (8/8 done)
+  |-- 010.01.01 ✓ Done       onboard-base
+  |-- 010.01.02 ✓ Done       task-load
+  |-- 010.01.03 ✓ Done       plan-task
+  |-- 010.01.04 ✓ Done       work-on-task
+  |-- 010.01.05 ✓ Done       pre-commit-review
+  |-- 010.01.06 ✓ Done       verify-test
+  |-- 010.01.07 ✓ Done       release-minor
+  \-- 010.01.08 ✓ Done       create-retro
+|-- 010.02   ✓ Done       work-on-8qm.t.5nx.1            yes    (8/8 done)
+# ... multiple tasks hidden
+012          ✓ Done       verify-test-suite
+015          ✓ Done       verify-e2e                     yes
+020          ✓ Done       release-minor
+025          ✓ Done       update-docs
+030          ✓ Done       create-pr
+040          ✓ Done       review-valid-1                 yes    (3/3 done)
+|-- 040.01   ✓ Done       review-pr
+|-- 040.02   ✓ Done       apply-feedback
+\-- 040.03   ✓ Done       release
+070          ✓ Done       review-fit-1                   yes    (3/3 done)
+|-- 070.01   ✓ Done       review-pr
+|-- 070.02   ✓ Done       apply-feedback
+\-- 070.03   ✓ Done       release
+100          ○ Pending    review-shine-1                 yes    (2/3 done)
+|-- 100.01   ✗ Failed     review-pr                              - Fork agent blocked by pre-existing unrelated changes (now stashed). Retrying.
+|-- 100.02   ✓ Done       apply-feedback
+\-- 100.03   ✓ Done       release
+101          ✓ Done       review-pr
+130          ✓ Done       reorganize-commits
+140          ✓ Done       push-to-remote
+150          ✓ Done       update-pr-desc                 yes
+155          ✓ Done       mark-tasks-done
+160          ✓ Done       create-retro
+161          ✓ Done       review-pr                      yes
+162          ✓ Done       apply-feedback                 yes
+163          ✓ Done       release                        yes
+```
+
+
+The easiest way to start is through [ace-overseer](../ace-overseer) -- define a task and run `ace-overseer work-on --task <ref> --preset work-on-task` , which creates the assignment, worktree, and tmux window in one shot.
+
+## How It Works
+
+1. Define steps from a [preset](.ace-defaults/assign/presets/work-on-task.yml) or compose from the [step catalog](.ace-defaults/assign/catalog/steps/) -- steps can nest into substeps and reference workflow instructions for execution details.
+2. Expand the definition into a session with explicit per-step instructions, state tracking (`pending` → `in_progress` → `done`/`failed`), and numbered hierarchy (e.g., `010`, `010.01`, `010.01.01`).
+3. Drive execution with `/as-assign-drive` -- fork long-running steps to isolated agent subprocesses, advance the queue on completion, and retry or inject fix steps on failure.
+
+## Use Cases
+
+**Define assignments from presets** - pick a [preset](.ace-defaults/assign/presets/) like [`work-on-task`](.ace-defaults/assign/presets/work-on-task.yml) or `release-only`, pass parameters (task refs, packages), and [`ace-assign create`](docs/usage.md) expands it into a concrete step queue. Steps are defined in the [catalog](.ace-defaults/assign/catalog/steps/) (e.g., [`work-on-task.step.yml`](.ace-defaults/assign/catalog/steps/work-on-task.step.yml)) and ordered by [composition rules](.ace-defaults/assign/catalog/composition-rules.yml). Compose custom assignments with `/as-assign-compose`.
+
+**Run with orchestrator and fork agents** - use `/as-assign-drive` to walk through steps, forking long-running work (implementation, review, release) to isolated agent subprocesses with configurable [execution defaults](.ace-defaults/assign/config.yml). Forks can run sequentially or as parallel batches, each producing inspectable traces and session reports under `.ace-local/assign/`.
+
+**Recover from failure without losing history** - keep failed-step lineage intact, inject targeted retries or fix steps, and continue execution with auditable failure evidence.
+
+**Compose assignments from templates** - use `/as-assign-compose` and `/as-assign-prepare` to build assignment plans from reusable patterns, then pair with [ace-task](../ace-task) for task lifecycle, [ace-bundle](../ace-bundle) for context loading, and [ace-review](../ace-review) for quality checks.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+desc "Run tests using ace-test"
+task :test do
+  sh "ace-test"
+end
+
+desc "Run tests directly (CI mode)"
+Minitest::TestTask.create(:ci)
+
+# Alias for CI compatibility
+task spec: :test
+task default: :test

data/docs/exit-codes.md

@@ -0,0 +1,61 @@
+---
+doc-type: user
+title: CLI Exit Codes
+purpose: Documentation for ace-assign/docs/exit-codes.md
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# CLI Exit Codes
+
+This document describes the exit codes returned by the `ace-assign` CLI.
+
+## Exit Code Reference
+
+| Code | Meaning | Example Scenario |
+|------|---------|------------------|
+| 0 | Success | Command executed successfully |
+| 1 | General error | Unhandled error, invalid step reference, finish rejected on stalled queue |
+| 2 | Assignment error | No active assignment or assignment not found |
+| 3 | Configuration not found | Config file does not exist |
+| 4 | Step not found | Referencing a step that does not exist |
+
+## Exit Code Details
+
+### Exit Code 0: Success
+The command executed successfully. This includes:
+- Creating an assignment (`create`)
+- Adding a step (`add`)
+- Retrying a step (`retry`)
+- Marking a step as failed (`fail`)
+- Displaying status (`status`)
+- Finishing a step (`finish`)
+
+### Exit Code 1: General Error
+An error occurred that doesn't fit into other categories:
+- Invalid step reference (e.g., `finish` with invalid step number)
+- Report rejected when queue is stalled (no step currently in progress)
+- Missing report input for `finish` (`--message` absent/blank and no piped stdin)
+- Other unhandled errors
+
+### Exit Code 2: Assignment Error
+Assignment state is invalid for the requested command:
+- No active assignment exists. Commands that require an active assignment return this code:
+- `status` when no assignment has been created
+- `finish` when no assignment has been created
+- Assignment ID does not exist (for commands targeting a specific assignment)
+
+### Exit Code 3: Configuration Not Found
+A required configuration file could not be found:
+- Config file does not exist when running `create`
+
+### Exit Code 4: Step Not Found
+The requested step reference does not exist in the target assignment:
+- `retry` with unknown step number
+- Commands that target a specific missing step
+
+## See Also
+
+- [Usage Guide](usage.md) for full command reference
+- [Getting Started](getting-started.md) for tutorial

data/docs/getting-started.md

@@ -0,0 +1,121 @@
+---
+doc-type: user
+title: Getting Started with ace-assign
+purpose: Tutorial for creating, running, and adapting assignment queues with ace-assign.
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-assign
+
+Use `ace-assign` to run multi-step work as a durable queue instead of ad-hoc notes.
+
+## Prerequisites
+
+- Ruby 3.2+
+- `ace-assign` installed
+- A writable project directory
+
+## Installation
+
+
+```bash
+gem install ace-assign
+```
+
+## 1) Create your first assignment
+
+Create `job.yaml`:
+
+
+```yaml
+assignment:
+  name: docs-update
+  description: Update package documentation
+
+steps:
+  - name: onboard
+    instructions: |
+      Load context with `ace-bundle project-base`.
+
+  - name: implement
+    instructions: |
+      Apply documentation updates.
+
+  - name: verify
+    instructions: |
+      Run lint and tests.
+```
+
+Create the assignment:
+
+
+```bash
+ace-assign create job.yaml
+```
+
+## 2) Check status and execute work
+
+
+```bash
+ace-assign status
+ace-assign finish --message onboard.md
+ace-assign status
+```
+
+Use `--message <file>` to keep reports explicit and reusable.
+
+## 3) Add work dynamically
+
+
+```bash
+ace-assign add fix-links --instructions "Fix broken docs links"
+ace-assign add verify-links --after 020 --child -i "Check all markdown links"
+```
+
+Use `--child` to insert nested steps under a parent step.
+
+## 4) Work with hierarchical steps
+
+- Parent steps complete when all children are done.
+- Queue traversal prioritizes pending children before siblings.
+- Renumbering cascades when inserting siblings in occupied ranges.
+
+Use status views:
+
+
+```bash
+ace-assign status
+ace-assign status --flat
+```
+
+## 5) Use scoped assignment targeting
+
+If you manage multiple assignments (or a subtree), always scope commands:
+
+
+```bash
+ace-assign status --assignment abc123@010.01
+ace-assign finish --message report.md --assignment abc123@010.01
+```
+
+## Common Commands
+
+| Command | Purpose |
+|---------|---------|
+| `ace-assign create job.yaml` | Create assignment from YAML |
+| `ace-assign status` | Show current queue |
+| `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 |
+| `ace-assign add NAME -i "..."` | Insert new step dynamically |
+| `ace-assign retry 040` | Retry failed step as linked work |
+| `ace-assign fork-run --root 010.01` | Execute a subtree in forked context |
+
+## Next steps
+
+- [Usage Guide](usage.md) for full command reference
+- [Handbook Reference](handbook.md) for skills/workflows inventory
+- [Fork Context Guide](../handbook/guides/fork-context.g.md) for delegation and recovery patterns
+- Runtime help: `ace-assign --help`

data/docs/handbook.md

@@ -0,0 +1,40 @@
+---
+doc-type: user
+title: ace-assign Handbook Reference
+purpose: Skill and workflow catalog shipped with ace-assign.
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-assign Handbook Reference
+
+Canonical skills and workflow instructions bundled with `ace-assign`.
+
+## Skills
+
+| Skill | What it does |
+|-------|---------------|
+| `as-assign-compose` | Compose a tailored assignment from catalog steps and composition rules |
+| `as-assign-create` | Create assignments from public workflow, with optional handoff to drive |
+| `as-assign-drive` | Drive active assignment execution step-by-step |
+| `as-assign-prepare` | Legacy/internal helper for preparing job specs |
+| `as-assign-run-in-batches` | Build repeated-item fan-out assignments from templates and item lists |
+| `as-assign-start` | Legacy compatibility wrapper routing create then drive |
+
+## Workflow Instructions
+
+| Protocol Path | Purpose | Invoked by |
+|---------------|---------|------------|
+| `wfi://assign/compose` | Compose assignment definitions from cataloged steps | `as-assign-compose` |
+| `wfi://assign/create` | Create assignment and initialize queue from config | `as-assign-create` |
+| `wfi://assign/drive` | Execute active assignment loop with status/finish/fail transitions | `as-assign-drive` |
+| `wfi://assign/prepare` | Legacy preset/informal instructions to job spec preparation | `as-assign-prepare` |
+| `wfi://assign/run-in-batches` | Generate a repeated-item batch assignment | `as-assign-run-in-batches` |
+| `wfi://assign/start` | Legacy orchestration entrypoint for create+drive | `as-assign-start` |
+
+## Guides
+
+| Guide | Purpose |
+|-------|---------|
+| `fork-context.g.md` | Fork subtree design, delegation boundaries, and recovery practices |

data/docs/usage.md

@@ -0,0 +1,224 @@
+---
+doc-type: user
+title: ace-assign Usage Guide
+purpose: Complete command reference for ace-assign queue orchestration, hierarchy, and fork execution.
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-assign Usage Guide
+
+`ace-assign` manages assignment queues with explicit step states and optional hierarchy.
+
+## Command Integrity
+
+When documenting or automating `ace-*` flows, prefer direct commands and explicit report files.
+
+Recommended:
+
+
+```bash
+ace-assign finish --message report.md
+```
+
+## Core Lifecycle
+
+
+```bash
+ace-assign create job.yaml
+ace-assign status
+ace-assign finish --message step-010.md
+ace-assign status
+```
+
+Use scoped targeting when needed:
+
+
+```bash
+ace-assign status --assignment abc123@010.01
+ace-assign finish --message done.md --assignment abc123@010.01
+```
+
+## Hierarchical Steps
+
+### Numbering
+
+- Top-level: `010`, `020`, `030`
+- Child: `010.01`, `010.02`
+- Grandchild: `010.01.01`
+
+### Rules
+
+- Parents auto-complete when all descendants are done.
+- Queue traversal works deepest actionable step first.
+- Inserted siblings can renumber later siblings (and descendants).
+
+Create child/sibling steps:
+
+
+```bash
+ace-assign add setup-db --after 010 --child -i "Set up DB"
+ace-assign add hotfix --after 010 -i "Urgent fix"
+```
+
+## Commands
+
+### `ace-assign create CONFIG`
+
+Create a new assignment from a YAML file.
+
+Options:
+
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign status`
+
+Show queue status for active or explicitly targeted assignment.
+
+Options:
+
+- `--flat, -f`
+- `--format table|json`
+- `--assignment <id>`
+- `--all, -a`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign start [STEP]`
+
+Start next workable pending step, or an explicit pending step in the active assignment.
+
+Options:
+
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign finish [STEP] --message VALUE`
+
+Complete current in-progress step (or explicit step in active assignment) with report content.
+
+`--message` accepts:
+
+- Inline text
+- File path
+
+Options:
+
+- `--message, -m` (required)
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign fail --message TEXT`
+
+Mark current step as failed.
+
+Options:
+
+- `--message, -m` (required)
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign add NAME`
+
+Insert a new step dynamically.
+
+Options:
+
+- `--instructions, -i TEXT`
+- `--after, -a NUMBER`
+- `--child, -c`
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign retry STEP_REF`
+
+Create a linked retry step for a failed step.
+
+Options:
+
+- `--assignment <id>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign fork-run`
+
+Execute a fork-enabled subtree in an isolated process.
+
+Options:
+
+- `--root <step-number>`
+- `--assignment <id>`
+- `--provider <provider:model>`
+- `--cli-args <args>`
+- `--timeout <seconds>`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign list`
+
+List assignments.
+
+Options:
+
+- `--all, -a`
+- `--task, -t <taskref>`
+- `--tree`
+- `--format table|json`
+- `--quiet, -q`
+- `--debug, -d`
+
+### `ace-assign select [ID]`
+
+Select active assignment or clear selection.
+
+Options:
+
+- `--clear`
+- `--quiet, -q`
+- `--debug, -d`
+
+## Workflow Patterns
+
+### Scoped Subtree Execution
+
+
+```bash
+ace-assign status --assignment abc123@010.01
+ace-assign fork-run --assignment abc123@010.01
+```
+
+### Recovery from Failure
+
+
+```bash
+ace-assign fail --message "Lint failed in docs"
+ace-assign retry 040 --assignment abc123
+```
+
+### Multi-assignment Management
+
+
+```bash
+ace-assign list --all
+ace-assign select abc123
+ace-assign select --clear
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Assignment error |
+| 3 | Configuration not found |
+| 4 | Step not found |
+| 130 | Interrupted (SIGINT) |
+
+See [exit-codes.md](exit-codes.md) for complete descriptions.

data/exe/ace-assign

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/assign"
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  exit_code = Ace::Assign::CLI.start(args)
+  exit(exit_code) if exit_code.nonzero?
+rescue Ace::Support::Cli::Error => e
+  warn e
+  exit(e.exit_code)
+end