# Workflow Testing Guide

This guide defines how to test workflow-layer changes (orchestrators + workflow agents).

Use the fixture project under `projects/project-a`.

## Standard Setup

### 1) Create an isolated run copy

```bash
cp -R ./projects/project-a /tmp/mixer-run
```

### 2) Sync runtime settings + skill into the run copy

```bash
python3 -m mixersystem sync --project_root=/tmp/mixer-run
```

## Regression Matrix

### A) Task workflow

Run local-mode task creation:

```bash
python3 -m mixersystem run task \
  --project_root=/tmp/mixer-run \
  --work_folder=./tasks/test-run \
  --task_id=local-002 \
  --description="Task workflow regression test" \
  --modules=all \
  --sync=false \
  --size=S
```

Validate:

- `task.md` exists in the work folder
- frontmatter contains `id` and `modules`
- no `target_modules` usage appears

### B) Plan workflow (single branch)

```bash
python3 -m mixersystem run plan \
  --project_root=/tmp/mixer-run \
  --work_folder=./tasks/test-001 \
  --size=S \
  --plan_builder_provider=claude \
  --branch_count=1 \
  --max_revisions=2
```

Validate:

- `plan.md` is produced
- review loop behavior matches `max_revisions`
- formatter runs (final plan structure is normalized)

### C) Plan workflow (branched)

```bash
python3 -m mixersystem run plan \
  --project_root=/tmp/mixer-run \
  --work_folder=./tasks/test-002 \
  --size=S \
  --plan_builder_provider=claude \
  --branch_count=2 \
  --max_revisions=1
```

Validate:

- branch folders are created under work folder `branches/`
- merged root `plan.md` is present
- failures surface as exceptions, not silent status values

### D) Module workflow

If the task has only a starter draft, normalize it first:

```bash
cp /tmp/mixer-run/tasks/test-003/plan-1-claude.md /tmp/mixer-run/tasks/test-003/plan.md
```

Then run:

```bash
python3 -m mixersystem run module \
  --project_root=/tmp/mixer-run \
  --work_folder=./tasks/test-003 \
  --size=S \
  --max_test_iterations=3 \
  --auto_commit=false \
  --auto_merge=false
```

Validate:

- `module.md` exists
- top `# Build Status` block is present and coherent
- tester loop stops at configured max
- terminal failure path raises with updated status block

## Log Review Checklist

- `trace.log`: expected agent sequence and loop counts
- `raw.log`: prompt/context correctness and output-format compliance
- `trace.md`: structured start/end records for post-run audit
