ace-assign 0.71.0 → 0.73.0

data/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1> ACE - Assign </h1>
 
-  Multi-step assignment execution with nesting, fork delegation, and inspectable traces.
+  Multi-step assignment plans with nesting, fork delegation, and inspectable state.
 
   <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
@@ -14,54 +14,81 @@
 
 > Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
 
+> **State owner:** `.ace-local/assign/` -- assignment plans and step state owned
+> by `ace-assign`. There is no second queue: the plan is the only place steps
+> live, and coworker configuration or the private overseer list never copy
+> them. The canonical flow is [docs/lab-flow.md](../docs/lab-flow.md).
+
 [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` turns work into a multi-step assignment with nested substeps and
+fork delegation. Steps come from a [step catalog](.ace-defaults/assign/catalog/steps/)
+and are assembled via [presets](.ace-defaults/assign/presets/work-on-task.yml) or
+composed manually. Each step may reference a workflow instruction for execution
+details. Assignments are restartable: failed steps keep their lineage so you can
+retry or inject fixes without losing history.
 
-❯ ace-assign status
-8qm5rt work-on-task-8qm.t.5nx-job.yml | running | 64/71 done | current: 100.01 review-pr | last: 070.03 release
-hidden: 66 | done: 64 active: 1 pending: 5 failed: 1
-100.01 active review-pr
-100.02 next apply-feedback
-100.03 next release
-130 next reorganize-commits
-140 next push-to-remote
+```bash
+ace-assign status
+# abc123 work-on-task-abc456 | running | 4/7 done | current: 100 review-pr
 ```
 
-Use `ace-assign status --mode full` when you need the whole tree, and `ace-assign step` when you need the raw instructions for the current or next step.
+Use `ace-assign status --mode full` for the whole tree and `ace-assign step` for
+the current or next step instructions.
 
+The local lifecycle is:
 
-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 terminal window in one shot.
+1. `ace-assign create` expands a preset or YAML definition into numbered steps
+   (`010`, `010.01`, …) with `pending` → `in_progress` → `done`/`failed` state.
+2. `ace-assign step` / `start` / `finish` / `fail` drive one step at a time;
+   `/as-assign-drive` wraps this loop for agents.
+3. `ace-assign add` / `retry` / `fork-run` adapt the plan while it runs.
 
-## Testing Contract
+The easiest way to start is through [ace-overseer](../ace-overseer):
+`ace-overseer work-on --task <ref>` creates the worktree, assignment, and
+terminal in one shot.
 
-- `ace-test ace-assign` runs the default deterministic package loop (`test/fast`).
-- `ace-test ace-assign feat` runs deterministic feature/contract coverage (`test/feat`).
-- `ace-test ace-assign all` runs full package deterministic coverage (`fast` + `feat`).
-- `ace-test-e2e ace-assign` runs scenario workflows under `test/e2e`.
+## Use Cases
 
-Assignment verification uses deterministic commands only:
-- modified packages: `ace-test <package> all --profile 6`
-- monorepo gate: `ace-test-suite --target all`
+**Define assignments from presets** - pick a preset such as `work-on-task` or
+`release-only`, pass parameters (task refs, packages), and run
+`ace-assign create --task ...` or `ace-assign create --yaml ...`. Steps are
+ordered by [composition rules](.ace-defaults/assign/catalog/composition-rules.yml).
 
-## How It Works
+**Run with orchestrator and fork agents** - `/as-assign-drive` walks the steps
+and can fork long-running work to isolated agent subprocesses with configurable
+execution defaults or per-step `fork.provider` overrides. Fork traces and
+session reports stay under `.ace-local/assign/`.
 
-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.
+**Recover from failure without losing history** - keep failed-step lineage,
+inject targeted retries or fix steps, and continue.
 
-## Use Cases
+**Compose assignments from templates** - use `/as-assign-compose` to build 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.
+
+## Planned waves
 
-**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 run `ace-assign create --task ...` or [`ace-assign create --yaml ...`](docs/usage.md) to expand them 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`.
+> **L3 status:** `ace-coworker` consumes an assignment from
+> `.ace-local/coworker/`, drives it through this gem's CLI, records results
+> in the task folder, and reports through `ace-hitl`. Resume after
+> interruption is the remaining L3 leaf.
+>
+> **Planned (L5.5):** role rules, review rounds, and forge delivery workflow --
+> not available yet.
 
-`work-on-task` release steps resolve `wfi://release/publish` from shipped workflow sources by default, and project-level `wfi://` source overrides registered under `.ace/nav/protocols/wfi-sources/` are honored by both `ace-bundle` and `ace-assign`.
+## Testing Contract
 
-**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) or per-step `fork.provider` overrides. Forks can run sequentially or as parallel batches, each producing inspectable traces and session reports under `.ace-local/assign/`.
+- `bin/ace-test ace-assign` runs the default deterministic package loop.
+- `bin/ace-test ace-assign feat` runs deterministic feature/contract coverage.
+- `bin/ace-test ace-assign all` runs full package deterministic coverage.
+- `bin/ace-test-e2e ace-assign` runs scenario workflows.
 
-**Recover from failure without losing history** - keep failed-step lineage intact, inject targeted retries or fix steps, and continue execution with auditable failure evidence.
+Assignment verification uses deterministic commands only:
 
-**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.
+- modified packages: `bin/ace-test <package> all --profile 6`
+- monorepo gate: `bin/ace-test-suite --target all`
 
 ---
 [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/docs/exit-codes.md

@@ -1,71 +1,63 @@
 ---
 doc-type: user
 title: CLI Exit Codes
-purpose: Documentation for ace-assign/docs/exit-codes.md
+purpose: Exit codes for the local ace-assign lifecycle commands.
 ace-docs:
-  last-updated: 2026-03-18
-  last-checked: 2026-03-21
+  last-updated: 2026-10-17
+  last-checked: 2026-10-17
 ---
 
 # CLI Exit Codes
 
-This document describes the exit codes returned by the `ace-assign` CLI.
+Exit codes returned by the local `ace-assign` lifecycle commands.
 
 ## 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 |
-| 5 | Attempt error | Attempt conflict, rejected receipt, unauthorized identity, unavailable evidence, or illegal attempt state |
+| 0 | Success | `create`, `add`, `retry`, `fail`, `status`, `step`, `start`, `finish` completed |
+| 1 | General error | Invalid step reference, report rejected when no step is in progress, missing report input, unhandled error |
+| 2 | Assignment error | No active assignment or unknown assignment ID |
+| 3 | Configuration not found | Required config file is missing during `create` |
+| 4 | Step not found | `retry` or another command references a step that does not exist |
+| 5 | Lifecycle conflict or busy maintenance | A prune/start exclusion blocks the operation: conflicting lifecycle identity, unsafe exclusion artifacts, or a busy/expired maintenance exclusion |
+| 130 | Interrupted | SIGINT during a command |
 
 ## 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)
+
+- `finish` with an invalid step number
+- `finish` when no step is in progress
+- `finish` with no report content (`--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)
+
+- No active assignment for a command that needs one (`status`, `finish`)
+- `--assignment` names an assignment that does not exist
 
 ### Exit Code 3: Configuration Not Found
-A required configuration file could not be found:
-- Config file does not exist when running `create`
+
+`create` cannot read the required configuration or YAML input.
 
 ### 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
-
-### Exit Code 5: Attempt Error
-An attempt, receipt, identity, or evidence problem rejected the operation:
-- `attempt start` with a conflicting binding for an owned subtree
-- `attempt finish`/`attempt reconcile` with a receipt that fails verification (wrong binding, stale head, digest mismatch, self-approval, forbidden fields)
-- Worker-identity attempts to accept a succeeded verdict
-- Unknown or missing execution-boundary identity
-- Reconciling a terminal attempt, or resolving uncertainty without a receipt
-- Unavailable or unwritable evidence storage blocking a managed effect
+
+The requested step reference does not exist in the target assignment.
+
+### Exit Code 5: Lifecycle Conflict or Busy Maintenance
+
+A local prune/start exclusion refused the operation:
+
+- `LifecycleErrors::Conflict` -- the lifecycle identity was pruned or its
+  exclusion artifacts are unsafe, so a writer must not be started against it.
+- `LifecycleErrors::MaintenanceBusy` -- the maintenance exclusion is busy or its
+  admission deadline expired.
+
+The command is refused; there is no retry loop. Inspect and clear the exclusion
+state, then rerun the operation explicitly.
 
 ## See Also
 
-- [Usage Guide](usage.md) for full command reference
-- [Getting Started](getting-started.md) for tutorial
+- [Usage Guide](usage.md) for the full command reference
+- [Getting Started](getting-started.md) for a tutorial

data/docs/getting-started.md

@@ -1,15 +1,20 @@
 ---
 doc-type: user
 title: Getting Started with ace-assign
-purpose: Tutorial for creating, running, and adapting assignment queues with ace-assign.
+purpose: Tutorial for creating, running, and adapting local assignment plans with ace-assign.
 ace-docs:
-  last-updated: 2026-03-22
-  last-checked: 2026-03-22
+  last-updated: 2026-10-17
+  last-checked: 2026-10-17
 ---
 
 # Getting Started with ace-assign
 
-Use `ace-assign` to run multi-step work as a durable queue instead of ad-hoc notes.
+> **State owner:** `.ace-local/assign/` -- assignment plans and step state owned
+> by `ace-assign`. Steps are never copied into a second queue. See
+> [docs/lab-flow.md](../../docs/lab-flow.md).
+
+Use `ace-assign` to run multi-step work as a durable local plan instead of
+ad-hoc notes.
 
 ## Prerequisites