ace-assign 0.37.0

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

@@ -0,0 +1,469 @@
+---
+doc-type: workflow
+title: Prepare Assignment Workflow
+purpose: workflow instruction for preparing ace-assign job configurations
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# Prepare Assignment Workflow
+
+## Purpose
+
+Transform informal instructions OR preset names into a structured job.yaml file that can be used with `ace-assign create job.yaml`. This workflow bridges the gap between high-level intent and the structured work queue format.
+
+## Input Formats
+
+The workflow accepts three input types:
+
+### 1. Preset Name Only
+
+```
+/as-assign-prepare work-on-task --taskref 123
+```
+
+Loads the preset and injects parameter values.
+
+### 2. Informal Instructions Only
+
+```
+/as-assign-prepare "Work on task 123, create a PR, do 2 review cycles"
+```
+
+Transforms prose into structured steps.
+
+### 3. Preset + Customization
+
+```
+/as-assign-prepare work-on-task --taskref 123 "skip onboarding, add security review"
+```
+
+Loads preset then applies modifications.
+
+## Available Presets
+
+Presets are stored in `ace-assign/.ace-defaults/assign/presets/`:
+
+| Preset | Description |
+|--------|-------------|
+| `work-on-task` | Unified preset for single-task (`--taskref`) and batch (`--taskrefs`) execution |
+
+List available presets:
+```bash
+ls ace-assign/.ace-defaults/assign/presets/
+```
+
+## Preset File Format
+
+### Basic Preset
+
+```yaml
+name: preset-name
+description: What this preset does
+
+parameters:
+  taskref:
+    required: true
+    description: Task reference (e.g., task-123 or 123)
+  pr_number:
+    required: false
+    description: Optional PR number for review steps
+
+steps:
+  - name: step-name
+    skill: ace_skill_name  # Optional skill reference
+    instructions:
+      - Step instruction line one.
+      - "Step instruction with {{parameter}} placeholder."
+```
+
+### Preset with Expansion Directives
+
+For multi-task presets, use the `expansion` section to generate hierarchical steps:
+
+```yaml
+name: work-on-task
+description: Work on multiple tasks with consolidated review
+
+parameters:
+  taskrefs:
+    required: true
+    type: array  # Accepts comma-separated, range, or pattern
+    description: Task references (e.g., "148,149,150" or "148-152")
+
+expansion:
+  batch-parent:
+    name: batch-tasks
+    number: "010"
+    instructions: |
+      Batch container - auto-completes when children done.
+      Tasks: {{taskrefs}}
+
+  foreach: taskrefs  # Parameter name to iterate over
+  child-template:
+    name: "work-on-{{item}}"  # {{item}} is current iteration value
+    parent: "010"
+    context: fork  # Parent split step can be forked (children stay non-fork)
+    instructions: |
+      Implement task {{item}} per specification.
+
+steps:
+  # Steps after expansion are appended with their own numbers
+  - name: consolidated-review
+    number: "020"
+    instructions: Review all batch changes.
+```
+
+#### Array Parameter Syntax
+
+The `--taskrefs` parameter accepts multiple formats:
+
+| Format | Example | Result |
+|--------|---------|--------|
+| Comma-separated | `148,149,150` | Tasks 148, 149, 150 |
+| Range | `148-152` | Tasks 148, 149, 150, 151, 152 |
+| Pattern | `240.*` | All subtasks of 240 |
+
+#### Generated Job Structure
+
+For `--taskrefs 148,149,150`, expansion generates:
+
+```
+010 batch-tasks (parent, auto-completes)
+├── 010.01 work-on-148 (fork context on split parent)
+│   ├── 010.01.01 onboard (no fork marker)
+│   ├── 010.01.02 plan-task (no fork marker)
+│   └── 010.01.03 work-on-task (no fork marker)
+├── 010.02 work-on-149 (fork context on split parent)
+└── 010.03 work-on-150 (fork context on split parent)
+020 consolidated-review
+030 finalize
+```
+
+The hierarchical numbering enables:
+- Parent auto-completion when all children are done
+- Parent-only fork markers for subtree delegation
+- Progress tracking per-task
+
+## Parameter Placeholders
+
+Use `{{parameter}}` syntax in preset instructions:
+- `{{taskrefs}}` - Task references (single-item or multi-item list)
+- `{{pr_number}}` - PR number (when available)
+
+Parameters are injected when preparing the job.yaml.
+
+## Transformation Rules
+
+### From Informal Instructions
+
+When parsing informal instructions, identify:
+
+1. **Task References**: "task 123", "task-123", "#123"
+2. **Skill Keywords**: Map to known skills
+   - "work on task" → `ace:task-work`
+   - "create pr", "make pr" → `ace:github-pr-create`
+   - "review", "review pr" → `ace:review-pr`
+   - "commit" → `ace:git-commit`
+   - "onboard" → `onboard`
+3. **Loop Indicators**: "2 cycles", "3 iterations", "twice"
+4. **Sequence Markers**: "then", "after that", "finally"
+
+### Loop Expansion
+
+Review loops expand into forked cycle parent steps with standard child sub-steps:
+
+```yaml
+# "do 3 review cycles" becomes:
+- name: review-valid-1
+  context: fork
+  sub_steps: [review-pr, apply-feedback, release]
+  instructions:
+    - "Child review-pr: use preset code-valid."
+    - "Focus: correctness — bugs, logic errors, missing functionality, broken contracts."
+
+- name: review-fit-1
+  context: fork
+  sub_steps: [review-pr, apply-feedback, release]
+  instructions:
+    - "Child review-pr: use preset code-fit."
+    - "Focus: quality — performance, architecture, standards, test coverage."
+
+- name: review-shine-1
+  context: fork
+  sub_steps: [review-pr, apply-feedback, release]
+  instructions:
+    - "Child review-pr: use preset code-shine."
+    - "Focus: polish — simplification, naming, documentation (non-blocking suggestions)."
+```
+
+## Process Steps
+
+### 1. Parse Input
+
+Determine input type:
+- If starts with known preset name → load preset
+- If contains `--taskref` or similar flags → extract parameters
+- If quoted string or prose → parse as informal instructions
+
+### 2. Load Preset (if applicable)
+
+```bash
+# Read preset file
+cat ace-assign/.ace-defaults/assign/presets/<preset-name>.yml
+```
+
+### 3. Extract Parameters
+
+From command-line flags:
+- `--taskref 123` → normalize to `taskrefs: ["123"]` (single task shorthand)
+- `--taskrefs 148,149,150` → `taskrefs: ["148", "149", "150"]` (multi-task)
+- `--taskrefs 148-152` → `taskrefs: ["148", "149", "150", "151", "152"]` (range)
+- `--output custom-job.yaml` → output path
+
+From informal instructions:
+- "task 123" → `taskrefs: ["123"]`
+- "tasks 148, 149, 150" → `taskrefs: ["148", "149", "150"]`
+- "PR 45" → `pr_number: "45"`
+
+### 4. Apply Customizations (if prose provided)
+
+Parse modifications:
+- "skip onboarding" → remove onboard step
+- "add security review" → insert security review step
+- "only 2 cycles" → adjust loop count
+
+### 5. Expand and Inject Parameters
+
+For presets with `expansion` section, use `Ace::Assign::Atoms::PresetExpander.expand()`:
+
+```ruby
+require "ace/assign"
+
+preset = YAML.load_file("work-on-task.yml")
+params = { "taskrefs" => ["148", "149", "150"], "review_preset" => "batch" }
+steps = Ace::Assign::Atoms::PresetExpander.expand(preset, params)
+```
+
+### 5.1 Resolve Skill `assign.source` Metadata (Deterministic Runtime Expansion)
+
+After preset expansion, each step with a `skill:` field may declare assignment source metadata via the skill frontmatter:
+
+```yaml
+assign:
+  source: wfi://task/work
+```
+
+Resolution flow:
+1. Find `SKILL.md` by step `skill` name (e.g., `ace:task-work`)
+2. Read `assign.source` from skill frontmatter
+3. Resolve `wfi://...` to workflow file
+4. Parse workflow frontmatter `assign.sub-steps`
+5. Materialize those sub-steps into the concrete job steps
+
+This keeps lifecycle ownership in workflow files while prepare/create remain deterministic.
+Compose intentionally does not perform this metadata scan.
+
+This generates hierarchical steps with:
+- Pre-assigned numbers (010, 010.01, 010.02, etc.)
+- Parent-child relationships
+- All `{{placeholder}}` tokens resolved
+
+For standard presets (no expansion), replace `{{parameter}}` placeholders:
+
+```yaml
+# Before
+instructions:
+  - "Work on task {{taskref}}."
+
+# After (with taskref=123)
+instructions:
+  - Work on task 123.
+```
+
+### 6. Validate Job Configuration
+
+Check:
+- [ ] Session name is set
+- [ ] All required parameters have values
+- [ ] No unresolved `{{placeholder}}` tokens remain
+- [ ] Steps have names and instructions
+- [ ] Skill references are valid (if present)
+
+### 7. Generate job.yaml
+
+Write the final configuration:
+
+```yaml
+session:
+  name: <preset-name>-<taskref>
+  description: <preset description with context>
+
+steps:
+  - name: <step-name>
+    skill: <skill-reference>  # If present in preset
+    instructions:
+      - <resolved instruction line>
+  # ... more 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`)
+
+Custom output: Use `--output path/to/custom.yaml`
+
+Report:
+```
+Job configuration created: job.yaml
+
+Session: work-on-task-123
+Steps: 10 total
+  - onboard
+  - work-on-task
+  - create-pr
+  - review-cycle-1
+  - apply-feedback-1
+  - review-cycle-2
+  - apply-feedback-2
+  - review-cycle-3
+  - apply-feedback-3
+  - finalize
+
+Start assignment with: ace-assign create job.yaml
+```
+
+## Output Format
+
+### job.yaml Structure
+
+```yaml
+session:
+  name: work-on-task-123
+  description: Work on task 123 with PR and review cycles
+
+steps:
+  - name: onboard
+    skill: as-onboard
+    instructions:
+      - Onboard yourself to the codebase.
+      - Load context and understand the project structure.
+
+  - name: work-on-task
+    skill: as-task-work
+    instructions:
+      - Work on task 123.
+      - Implement the required changes following project conventions.
+
+  - name: create-pr
+    skill: as-github-pr-create
+    instructions:
+      - Create a pull request for the changes.
+      - Capture the PR number for subsequent review steps.
+      - Update the next steps with the PR number.
+
+  # ... more steps
+```
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Unknown preset | List available presets, ask for selection |
+| Missing required parameter | Prompt for value |
+| Invalid task reference | Show expected formats |
+| Unresolved placeholders | Report which parameters need values |
+
+## Examples
+
+### Example 1: Full Workflow Preset
+
+```
+/as-assign-prepare work-on-task --taskref 148
+```
+
+Creates job with 13 steps: onboard, work-on-task, release, create-pr, 2 review cycles (review + apply-feedback + release each), reorganize-commits, push-to-remote, update-pr-desc.
+
+### Example 2: Informal Instructions
+
+```
+/as-assign-prepare "implement task 148, create pr, review twice"
+```
+
+Parses instructions and creates job with:
+- onboard
+- work-on-task (148)
+- create-pr
+- review-valid-1 (fork subtree: review-pr → apply-feedback → release)
+- review-fit-1 (fork subtree: review-pr → apply-feedback → release)
+- finalize
+
+### Example 3: Custom Output Path
+
+```
+/as-assign-prepare work-on-task --taskref 148 --output .cache/my-job.yaml
+```
+
+Writes configuration to specified path.
+
+### Example 4: Multi-Task Batch (Comma-Separated)
+
+```
+/as-assign-prepare work-on-task --taskrefs 148,149,150
+```
+
+Creates job with hierarchical structure:
+- batch-tasks (010) - parent container
+  - work-on-148 (010.01) - fork context
+  - work-on-149 (010.02) - fork context
+  - work-on-150 (010.03) - fork context
+- consolidated-review (020)
+- finalize (030)
+
+### Example 5: Multi-Task Batch (Range)
+
+```
+/as-assign-prepare work-on-task --taskrefs 148-152
+```
+
+Expands range to tasks 148, 149, 150, 151, 152.
+
+### Example 6: Multi-Task Batch (Pattern)
+
+```
+/as-assign-prepare work-on-task --taskrefs "240.*"
+```
+
+Expands pattern to match subtasks (requires resolution at prepare time).
+
+## Success Criteria
+
+- [ ] Input correctly parsed (preset, parameters, or prose)
+- [ ] Preset loaded and parameters injected
+- [ ] Expansion directives processed (if present)
+- [ ] Hierarchical steps numbered correctly
+- [ ] Loops expanded into separate steps
+- [ ] All placeholders resolved
+- [ ] Valid job.yaml generated
+- [ ] Clear summary provided to user
+
+## Next Steps
+
+After job.yaml is created:
+
+```bash
+# Start the assignment
+/as-assign-create job.yaml
+
+# Or directly:
+ace-assign create job.yaml
+
+# Check status
+ace-assign status
+
+# Drive execution through the workflow
+/as-assign-drive
+```
+
+**Note:** Job files created in `<task>/jobs/` stay in place when `ace-assign create` runs. Files created elsewhere are moved to `<task>/jobs/<session_id>-job.yml` for provenance. Always use `ace-assign status` to query the current assignment state.

data/handbook/workflow-instructions/assign/recover-fork.wf.md

@@ -0,0 +1,233 @@
+---
+doc-type: workflow
+title: Fork Recovery Workflow
+purpose: Recover from fork-run failures — crash with partial completion, provider unavailability, or mixed subtree state
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Fork Recovery Workflow
+
+## Purpose
+
+Recover from `fork-run` failures during assignment execution. This workflow is invoked by the driver when a fork subtree exits non-zero. It covers three scenarios: crash with partial progress, provider unavailability, and mixed subtree state after provider failure.
+
+## Prerequisites
+
+- A fork subtree that exited non-zero (`fork-run` failed)
+- The driver has the `ASSIGNMENT_ID` and `FORK_ROOT` pinned
+- The driver has NOT started executing fork work inline (fork boundary intact)
+
+## Variables
+
+- `$ASSIGNMENT_ID`: The pinned assignment identifier
+- `$FORK_ROOT`: The root step number of the failed fork subtree (e.g., `020`)
+- `$failed_step`: The specific step that was active when the fork crashed
+
+## Detection: When to Use This Workflow
+
+Invoke this workflow when `fork-run` exits non-zero. Determine the scenario:
+
+| Signal | Scenario | Go to |
+|--------|----------|-------|
+| `exit != 0` AND (`git status --short` shows changes OR mixed step status) | Crash with partial progress | Scenario 1 |
+| `exit != 0` AND error indicates timeout/hang/empty response (no stack trace, no test failure) | Provider unavailability | Scenario 2 |
+| `exit != 0` AND subtree has mix of done + failed + pending children after provider failure | Mixed state after provider failure | Scenario 3 |
+
+---
+
+## Scenario 1: Crash with Partial Completion
+
+The fork crashed due to a code issue, environment error, or timeout — but made partial progress.
+
+### Step 1: Commit Partial Work
+
+Stage and commit any uncommitted changes from the crashed fork:
+
+```bash
+git add -A
+ace-git-commit -i "partial: save fork progress for ${FORK_ROOT}"
+```
+
+### Step 2: Write Progress Report for the Active Step
+
+Document what was accomplished and what remains:
+
+```bash
+cat > /tmp/partial-report.md << 'EOF'
+## Partial Completion (fork crashed)
+
+### Completed
+- [list of files created/modified]
+- [tests passing: X tests, Y assertions]
+
+### Remaining
+- [list of components not yet implemented]
+- [tests not yet written]
+EOF
+ace-assign finish --message /tmp/partial-report.md --assignment ${ASSIGNMENT_ID}@${failed_step}
+```
+
+### Step 3: Inject Recovery Steps
+
+Add two child steps inside the failed step's subtree. **Never inject as top-level siblings.**
+
+#### Recovery Step Construction Rules
+
+**recovery-onboard** — Must enumerate all completed subtree report paths explicitly:
+
+```bash
+# 1. List all completed reports in the subtree
+REPORT_DIR=".ace-local/assign/${ASSIGNMENT_ID}/reports"
+REPORT_LIST=$(ls ${REPORT_DIR}/${FORK_ROOT}.* 2>/dev/null | sort)
+
+# 2. Build the instruction with explicit file paths
+RECOVERY_INSTRUCTIONS="Read these reports to understand completed work before continuing:
+$(echo "$REPORT_LIST" | sed 's/^/- /')
+Also read the failure evidence from the failed step."
+
+# 3. Inject the step
+ace-assign add "recovery-onboard" --after ${failed_step} --child \
+  --assignment ${ASSIGNMENT_ID}@${FORK_ROOT} \
+  -i "$RECOVERY_INSTRUCTIONS"
+```
+
+The recovery-onboard instructions MUST list every report file path — not semantic references like "read the plan-task report". A forked recovery agent starts with zero context and cannot infer the directory structure.
+
+**continue-work** — Must be a verbatim copy of the original failed step's instructions:
+
+```bash
+# 1. Read the original failed step file
+STEP_FILE=$(ls .ace-local/assign/${ASSIGNMENT_ID}/steps/${failed_step}-*.st.md)
+
+# 2. Extract the instruction body (everything after YAML frontmatter)
+ORIGINAL_INSTRUCTIONS=$(sed '1,/^---$/{ /^---$/!d; /^---$/d }' "$STEP_FILE" | sed '1,/^---$/d')
+
+# 3. Inject continue-work with the SAME instructions
+ace-assign add "continue-work" --after recovery-onboard --child \
+  --assignment ${ASSIGNMENT_ID}@${FORK_ROOT} \
+  -i "$ORIGINAL_INSTRUCTIONS"
+```
+
+The continue-work step IS the restart of the same work — it needs the same execution rules, principles, conventions, and done criteria that the original agent had. Do NOT compress or summarize the instructions. Only the recovery-onboard step gets special "catch up" instructions.
+
+### Step 4: Reset Downstream Steps
+
+If any steps after the failed step were completed during a prior (incorrect) recovery attempt, reset them:
+
+- Set their status back to `pending` in the step file frontmatter
+- Delete their report files from `.ace-local/assign/${ASSIGNMENT_ID}/reports/`
+
+### Step 5: Re-Fork
+
+The injected recovery steps are pending, so `fork-run` will pick them up:
+
+```bash
+ace-assign fork-run --assignment ${ASSIGNMENT_ID}@${FORK_ROOT}
+```
+
+---
+
+## Scenario 2: Provider Unavailability
+
+The fork failed because the LLM provider timed out, hung, or returned no output — not because of a code bug. Re-forking would crash the same way.
+
+### Step 1: Confirm Provider Failure
+
+Read the fork's last message and failed step error. Look for:
+- Model timeout or API unavailability
+- Empty or truncated response
+- Connection reset or socket hangup
+- Tool hang with no output
+
+NOT provider failure: stack traces, test failures, syntax errors — those are code bugs (use Scenario 1).
+
+### Step 2: Classify the Failed Step
+
+| Step Type | Description | Example Steps |
+|-----------|-------------|---------------|
+| **LLM-tool step** | Invokes an LLM-backed tool as its primary action | `ace-review`, `ace-lint`, audit, summarize |
+| **Code step** | Produces or modifies source code | implement, fix, refactor, work-on-task |
+
+### Step 3: Fork-Side Action (if still inside fork)
+
+The fork MUST only fail and exit. It must NEVER inject steps:
+
+```bash
+# Mark the crashed step as failed with evidence, then exit
+ace-assign fail --message "Provider unavailable: <error details>" \
+  --assignment ${ASSIGNMENT_ID}@${failed_step}
+# EXIT — do not add steps, do not retry, do not modify the assignment tree
+```
+
+**Forks NEVER inject steps outside their subtree scope. Recovery decisions belong to the driver.**
+
+### Step 4: Driver-Side Recovery
+
+After detecting the fork failure, the driver classifies and recovers:
+
+**LLM-tool steps** → execute equivalent work inline at driver level:
+
+```bash
+# Option A: Execute inline (for LLM-tool steps only)
+# Read changed files, analyze each, write review report directly
+
+# Option B: Add retry as a child of the failed step's parent
+ace-assign add "retry-<step-name>" --after <failed_step> --child \
+  --assignment ${ASSIGNMENT_ID}@${FORK_ROOT} \
+  -i "Provider was unavailable for forked <step-name>. Execute equivalent work inline: <specific instructions>"
+```
+
+**Code steps** → do NOT execute inline. Wait for provider recovery or escalate:
+
+```bash
+# Ask user whether to wait and retry later
+# Do NOT attempt the code work inline — context isolation is required
+```
+
+**Inline execution constraint**: Only LLM-tool steps may go inline during provider unavailability. Code-producing steps always require a fork for context isolation — wait for recovery or ask the user.
+
+---
+
+## Scenario 3: Re-Fork After Partial Provider Failure
+
+The fork subtree has a mix of done, failed, and pending children after a provider failure. The driver recovers by re-forking — not by absorbing remaining work inline.
+
+### Protocol
+
+1. **Inject retry as a child** of the failed step's parent subtree (never as a top-level sibling):
+
+```bash
+ace-assign add "retry-<step-name>" --after ${failed_child} --child \
+  --assignment ${ASSIGNMENT_ID}@${FORK_ROOT} \
+  -i "Retry <step-name> after provider recovery."
+```
+
+2. **Re-fork the subtree** — fork-run re-enters and picks up pending/retry children:
+
+```bash
+ace-assign fork-run --assignment "${ASSIGNMENT_ID}@${FORK_ROOT}"
+```
+
+3. **Do NOT inject steps as top-level siblings** — retry steps must be children of the original subtree root, never top-level steps like `101` or `121`.
+
+**Anti-pattern**: Driver sees subtree 110 with 110.01 failed, 110.02 and 110.03 pending. Driver executes 110.02 and 110.03 inline. This defeats context isolation and violates the fork-delegation constraint.
+
+---
+
+## Key Principles
+
+1. **Never execute fork work inline** — except for LLM-tool steps during provider unavailability. The fork boundary exists for context isolation.
+2. **Recovery steps are always children, never top-level siblings** — injecting at the top level breaks subtree scope and causes downstream steps to run without prerequisite work.
+3. **Recovery-onboard lists explicit file paths** — never semantic references. The recovery agent has zero context.
+4. **Continue-work copies original instructions verbatim** — the restart needs the same rules as the original. Only recovery-onboard gets special instructions.
+5. **Reset downstream steps after incorrect recovery** — if steps ran without their prerequisite work, they must be reset to pending with their reports deleted.
+
+## Success Criteria
+
+- Failed fork subtree is recovered without breaking fork isolation
+- Recovery children are injected inside the correct subtree scope
+- Recovery agent receives explicit report paths and complete original instructions
+- Re-fork picks up pending recovery steps and completes the subtree
+- No fork work is absorbed into the driver (except LLM-tool inline during provider unavailability)