Cookbook

Create and complete a bug WU

pnpm wu:create \
  --title "Handle a missing auth user" \
  --lane "Framework: Core" \
  --type bug \
  --exposure backend-only \
  --description "Prevent the auth handler from throwing when the user lookup returns empty" \
  --acceptance "A missing user returns the anonymous response without throwing" \
  --notes "Preserve the existing authenticated response contract" \
  --code-paths "src/auth/handler.ts" \
  --test-paths-unit "src/auth/__tests__/handler.test.ts" \
  --test-paths-manual "Run the auth smoke request with an unknown user and verify the anonymous response"

# Use the generated ID.
pnpm wu:claim --id <wu-id> --lane "Framework: Core"
pnpm wu:brief --id <wu-id>
cd worktrees/framework-core-<wu-id>

# Implement, test, and commit in the worktree.
pnpm wu:prep --id <wu-id>

cd /path/to/main
pnpm wu:done --id <wu-id>
pnpm wu:verify --id <wu-id>

Work in parallel

Parallelize independent WUs across lanes or disjoint paths permitted by the configured WIP limit (lanes with no wip_limit are unlimited):

# Terminal 1
pnpm wu:claim --id <wu-id> --lane "Framework: Core"
pnpm wu:brief --id <wu-id>
cd worktrees/framework-core-<wu-id>

# Terminal 2
pnpm wu:claim --id <wu-id> --lane "Content: Documentation"
pnpm wu:brief --id <wu-id>
cd worktrees/content-documentation-<wu-id>

Phase numbers do not impose execution order. Use blocked_by relationships when one WU must wait for another.

Block, release, and resume

pnpm wu:block --id <wu-id> --reason "Waiting for the upstream API contract"
pnpm wu:unblock --id <wu-id>

# Hand ownership back without deleting the preserved lane branch.
pnpm wu:release --id <wu-id> --keep-branch

# The original assigned user continues the retained source with an ordinary claim: the branch,
# index and dirty bytes are kept, a fresh session is minted, and the lane gains one commit that
# records the new claim generation.
pnpm wu:claim --id <wu-id> --lane "<lane>"

# Another owner follows the recovery guidance before reclaiming.
pnpm wu:recover --id <wu-id> --action resume
pnpm wu:repair --id <wu-id> --claim

If a worktree is missing while its active lane branch remains intact, restore it without resetting the WU:

pnpm wu:recover --id <wu-id> --action restore

Rebase a long-running WU

Use the governed command. It refreshes the changed-file baseline after a successful rebase so unrelated files landed by other WUs do not contaminate completion gates.

cd worktrees/framework-core-<wu-id>
pnpm wu:rebase --id <wu-id>

Do not force-push a lane branch or hand-edit baseline_main_sha.

Diagnose gates

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm wu:prep --id <wu-id>

Only a specifically named, configured skippable gate with matching main-branch evidence can be skipped:

cd /path/to/main
pnpm wu:done --id <wu-id> \
  --skip-gate lane-health \
  --reason "The same unrelated failure is recorded on main" \
  --fix-wu <wu-id>

Danger

--skip-gates, --no-verify, raw force pushes, and destructive Git recovery are not lifecycle shortcuts. Fix introduced failures and use the named recovery commands.

Capture an unrelated discovery

Workers capture discoveries for triage; they do not create an unreviewed WU from inside the active worker session:

pnpm mem:create "Bug: payment handler rejects an empty card list" \
  --type discovery \
  --tags bug,scope-creep \
  --wu <wu-id>

pnpm mem:signal "Bug discovery captured for triage" --wu <wu-id> --intent INFO

Preserve context

pnpm mem:signal "RED test passes; implementing the adapter" --wu <wu-id>
pnpm mem:checkpoint --wu <wu-id>
pnpm mem:inbox --since 1h
pnpm wu:brief --id <wu-id>

Configure lanes and gates

Do not copy a legacy flat workspace.yaml block. Use managed commands and fully qualified pack keys:

pnpm lane:create \
  --name "Framework: Core" \
  --wip-limit 1 \
  --add-path "src/core/**"

pnpm lane:edit --name "Framework: Core" --add-path "src/shared/**"
pnpm config:set --key software_delivery.gates.execution.preset --value node
pnpm config:set --key software_delivery.gates.minCoverage --value 90
pnpm config:get --key software_delivery.gates

See Workspace Spec for the distinction between kernel lanes and Software Delivery lane definitions.

Clean abandoned work safely

# Preview first.
pnpm wu:prune
pnpm wu:prune --remote

# Execute only after reviewing the preview.
pnpm wu:prune --execute
pnpm wu:prune --remote --execute

Cleanup is lease-aware and records recoverable tracked removals. Raw git worktree prune is not the WU lifecycle authority.

Quick reference

Task	Command
Discover commands	pnpm lumenflow:commands
Check WU	pnpm wu:status --id WU-XXX
Prepare completion	pnpm wu:prep --id WU-XXX
Complete from main	pnpm wu:done --id WU-XXX
Verify completion	pnpm wu:verify --id WU-XXX
Inspect lane	pnpm lane:list --json
Save context	pnpm mem:checkpoint --wu WU-XXX

Next steps

• Work Units — authoring contract
• Troubleshooting — detailed recovery
• CLI Reference — generated command options