WU Prep Workflow

As of WU-1223, completing a Work Unit is a two-step process. This guide explains the new workflow.

Why Two Steps?

The previous single-step wu:done ran gates on main, which could cause issues with worktree isolation. The new workflow:

1. wu:prep runs gates in the worktree (where your changes are)
2. wu:done does merge and cleanup from main

This ensures gates validate your actual changes, not stale main code.

The Workflow

1. Work in your worktree

   Complete your implementation, write tests, commit changes.

2. Run wu:prep from worktree

   pnpm wu:prep --id WU-123

   This command:

   • Validates you’re in a worktree
   • Runs quality gates
   • Prints a copy-paste instruction for the next step

3. Run wu:done from main (copy-paste)

   Copy the command printed by wu:prep:

   cd /path/to/main && pnpm wu:done --id WU-123

   This command:

   • Validates you’re in main checkout
   • Fast-forward merges your changes
   • Creates completion stamp
   • Removes the worktree

Command Reference

wu:prep

Prepares a WU for completion by running gates in the worktree.

pnpm wu:prep --id WU-123 [--docs-only] [--full-tests]

Flag	Description
--id	WU ID (required)
--docs-only	Run docs-only gates (format, spec-linter)
--full-tests	Disable tests.unit scoping and run the default incremental/full test gate behavior

When the active preset supports path-scoped execution, wu:prep uses the current WU’s tests.unit entries to scope the test gate.

For presets that do not support path-scoped execution, such as dotnet, wu:prep falls back to the configured default test gate flow instead of trying a JavaScript-specific scoped runner.

When software_delivery.gates.delivery_review.enabled: true, wu:prep can also run the native delivery_review gate. Auto-run is controlled per client at software_delivery.agents.clients.<client>.features.delivery_review.auto_run.

Must be run from worktree - errors if run from main.

Native Delivery Review During wu:prep

delivery_review is a Software Delivery pack feature, not a vendor overlay. It uses the same canonical config that briefing and prompt surfaces consume.

wu:prep auto-runs delivery_review only when:

• software_delivery.gates.delivery_review.enabled is true
• the active runtime client has features.delivery_review.enabled: true
• the active runtime client has features.delivery_review.auto_run: true

Direct gate execution with pnpm gates uses the same config, but does not require auto_run: true.

The review writes a stable artifact at .lumenflow/artifacts/delivery-review/<WU-ID>.json with a portable verdict contract:

• PASS passes gates
• PARTIAL logs a warning and continues
• FAIL blocks wu:prep

The result is designed for any host or product to consume later. It does not require lumenflow-cloud, does not assume a specific agent vendor, and does not rename or overload wu:verify.

wu:done

Completes a WU by merging and cleaning up.

pnpm wu:done --id WU-123

Flag	Description
--id	WU ID (required)
--skip-gates	Skip gates (emergency only, requires —reason)

Must be run from main - errors if run from worktree.

Error Messages

wu:done from worktree

If you see “wu:done must be run from main checkout”, you ran wu:done from a worktree. Use wu:prep instead, then follow its copy-paste instruction.

wu:prep from main

If you see “wu:prep must be run from a worktree”, navigate to your worktree first with cd worktrees/<lane>-wu-xxx.

Migration Notes

Before WU-1223

# Old workflow (single step)
cd /path/to/main
pnpm wu:done --id WU-123  # Ran gates on main

After WU-1223

# New workflow (two steps)
# Step 1: From worktree
pnpm wu:prep --id WU-123

# Step 2: From main (copy-paste from wu:prep output)
cd /path/to/main && pnpm wu:done --id WU-123

Escalation Resolution

If a WU has escalation_triggers (e.g., sensitive_data, security_p0), wu:done blocks until the escalation is resolved. Use wu:escalate to check status or resolve:

# Check escalation status
pnpm wu:escalate --id WU-123

# Resolve escalation (uses git user.email)
pnpm wu:escalate --resolve --id WU-123

# Resolve with a specific approver email
pnpm wu:escalate --resolve --id WU-123 --resolver admin@example.com

Flag	Description
--id	WU ID (required)
--resolve	Resolve the escalation
--resolver	Override resolver email (defaults to git config)

After resolving, wu:done will succeed for escalation-triggered WUs.

FAQ

Can I skip wu:prep?

No. If you run wu:done from main without running wu:prep first, gates won’t have run in the worktree where your changes are. The previous behavior of running gates on main has been removed.

What if gates fail in wu:prep?

Fix the issues in your worktree, then run wu:prep again. The workflow prevents partial completions.

Do I still need --full-tests for .NET repos?

Usually no. For presets such as dotnet, wu:prep already falls back to the configured default test flow when path-scoped execution is unsupported. Use --full-tests when you want to force the default incremental/full flow even for presets that support scoped execution.

Does this change skip-gates?

If you need to use --skip-gates, run wu:done directly from main with the --reason flag. This is for emergency use only when pre-existing failures block completion.

What if gates fail on code I didn’t change?

As of v3.19.0 (WU-2357), wu:prep detects test failures that already exist on main. When all blockers are pre-existing, it prints a ready-to-copy command:

cd /path/to/main && pnpm wu:done --id WU-XXX --skip-gates --reason "pre-existing on main" --fix-wu WU-YYY

New failures introduced by your changes remain blocking and must be fixed first. See Troubleshooting: Pre-existing gate failures for the full verification workflow.