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

By default, wu:prep uses the current WU’s tests.unit entries to scope the test gate.

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

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.

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.