WU Prep Workflow

Completing a Work Unit is a two-step process. This guide explains the 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
   • Runs configured external work-item close-out/readback hooks after successful local completion
   • 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 globally by software_delivery.gates.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. Enforcement is registered from the global gate config and behaves the same for Claude, Codex, Cursor, Windsurf, Cline, Aider, custom agents, and hosted cloud workers.

wu:prep auto-runs delivery_review only when:

• software_delivery.gates.delivery_review.enabled is true
• software_delivery.gates.delivery_review.auto_run is true
• the WU type does not match software_delivery.gates.delivery_review.skip_types

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

Legacy client-scoped software_delivery.agents.clients.<client>.features.delivery_review blocks are accepted for one release and emit a migration warning. They may still be used for adapter UX or prompt hints, but they are not the core enforcement switch.

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. See the Gates Reference for the catalogue entry, skippability default, and artifact contract.

wu:done

Completes a WU by merging and cleaning up.

pnpm wu:done --id WU-123

| Flag | Description | | -------------------- | ------------------------------------------------------------------------------------- | | --id | WU ID (required) | | --skip-gate <name> | Skip one explicitly named skippable gate (repeatable; requires —reason and —fix-wu) |

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

External QA / Work-Item Close-Out

External systems are side effects, so LumenFlow treats them as lifecycle hooks instead of worker instructions. A worker may see external_work_items in wu:brief, but those items are context only. The safe sequence is:

1. wu:claim
2. wu:brief
3. implementation
4. verification / wu:prep
5. local wu:done
6. external close-out adapter
7. readback adapter
8. audit trail

If wu:prep fails, wu:done fails, or branch-pr mode only creates a PR, close-out does not run. When it does run, audit events are appended to .lumenflow/telemetry/external-closeout.ndjson.

Configure providers through config:set:

pnpm config:set --key software_delivery.external_work_items.enabled --value true
pnpm config:set --key software_delivery.external_work_items.providers.hub --json-value '{
  "closeout": {
    "kind": "command",
    "command": "pbis",
    "args": ["done", "{{item_id}}", "--status", "{{desired_status}}"]
  },
  "readback": {
    "kind": "command",
    "command": "pbis",
    "args": ["show", "{{item_id}}", "--json"],
    "status_json_path": "state.status"
  },
  "review": {
    "verdict_statuses": ["Pass", "Fail"],
    "worker_may_set_verdict": false
  },
  "rollback_guidance": "Reopen the item or move it out of review if readback diverges."
}'

Adapters may be command or api. Template variables available to adapters are {{wu_id}}, {{provider_id}}, {{item_id}}, {{desired_status}}, and {{lifecycle_intent}}.

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 two-step completion

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

After two-step completion

# 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 named gate skips?

Named --skip-gate <name> requests remain available for explicitly skippable gates with matching structured failure evidence on main. They require --reason and --fix-wu.

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

wu:prep probes the named gate against main. When structured evidence proves the same failure is pre-existing, you may request that specific skippable gate:

cd /path/to/main && pnpm wu:done --id WU-XXX --skip-gate <name> --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.