Work Units (WUs)

Name: LumenFlow
Author: The LumenFlow Project

A Work Unit (WU) is a small, well-defined piece of work with clear acceptance criteria and proof of completion.

Why WUs?

Traditional tickets are:

Vague (“Fix the login bug”)
Unbounded (no clear definition of done)
Trust-based (marked done without proof)

WUs are:

Specific (“Add email validation to login form”)
Bounded (completable in a single session, <50 tool calls)
Evidence-based (tests and artifacts prove completion)

Anatomy of a WU

id: WU-0042
title: Add email validation to login form
lane: 'Experience: UI'
type: feature
status: ready
priority: P2
exposure: ui

description: |
  Add client-side email validation before form submission.
  Show inline error message for invalid formats.

acceptance:
  - Email field validates on blur
  - Invalid emails show "Please enter a valid email"
  - Valid emails allow form submission
  - Unit test covers validation logic

test_paths:
  unit:
    - src/components/__tests__/login-form.test.ts
  e2e:
    - e2e/login.spec.ts

code_paths:
  - src/components/LoginForm.tsx
  - src/utils/validation.ts

Canonical WU IDs

Every Work Unit has a canonical id made of a configurable prefix and a zero-padded integer. Defaults preserve backward compatibility — every existing LumenFlow repo keeps emitting WU- prefixed ids without any config change.

Format rule

A canonical id is <prefix><zero-padded-integer> where:

prefix matches /^[A-Z][A-Z0-9]{1,9}-$/ (default 'WU-').
the integer body is at least width characters wide (default 4).
the integer body may be wider than width once the sequence overflows (e.g. WU-10000 is canonical even when width=4); the sequence never truncates.

wu:create canonicalizes --id input before any file is written — passing --id WU-14 writes WU-0014.yaml. Auto-generated ids are zero-padded too.

Collision protection

Two different string forms of the same integer cannot coexist: WU-14 and WU-0014 resolve to the same canonical integer and wu:create hard-errors if the integer is already represented anywhere on disk. The error ships with a copy-pasteable wu:rename remediation command.

Configuration

Canonical ID behaviour is controlled by software_delivery.wu_id.* in workspace.yaml:

software_delivery:
  wu_id:
    width: 4 # 1-6; default 4 → WU-0001
    strict: true # enforce canonical format at creation; lumenflow:doctor --deep flags drift
    prefix: 'WU-' # pattern /^[A-Z][A-Z0-9]{1,9}-$/; try TASK-, STORY-, TICKET-, …

Default (`WU-`) example

# Fresh repo, no config changes — auto-generated ids are WU-0001, WU-0002, …
pnpm wu:create --lane "Experience: UI" --title "Add login form" …
# ↳ WU-0001

# --id input is canonicalized before any file is written:
pnpm wu:create --id WU-14 --title "…"
# ↳ writes WU-0014.yaml with id: WU-0014

Vendor-neutral prefix example (`TASK-`)

Teams that prefer a non-WU- prefix can pick a different one without touching any WU source file:

pnpm config:set --key software_delivery.wu_id.prefix --value TASK-
pnpm wu:create --lane "Experience: UI" --title "Add login form" …
# ↳ TASK-0001

pnpm wu:create --id TASK-14 --title "…"
# ↳ writes TASK-0014.yaml with id: TASK-0014

Legacy drift and `wu:rename`

pnpm lumenflow:doctor --deep flags any WU YAML whose id is valid but not canonical (e.g. WU-5.yaml when width=4). Offenders come with copy-pasteable repair commands:

pnpm wu:rename --from WU-5 --to WU-0005

wu:rename moves the YAML, rewrites the id: field, moves the .done stamp, appends a wu_renamed event to .lumenflow/state/wu-events.jsonl, and regenerates backlog.md and status.md. When a downstream repo has already canonicalized its YAML out-of-band but the generated views still regenerate with legacy ids, use --replay-only to append the event without touching the filesystem:

pnpm wu:rename --from WU-5 --to WU-0005 --replay-only

Either form is append-only — history is never rewritten. Historical events retain their original wuId; a replay-time projection resolves them to the new canonical id so generated views only show the post-rename form.

Strict vs permissive mode

strict: true (default) — lumenflow:doctor --deep treats drift as exit code 1, wu:rename’s CLI guard refuses a non-canonical --to.
strict: false — legacy unpadded ids are tolerated (warning-only). Use this as a migration ramp for repos that cannot normalize in one go; integer-level collision detection still hard-blocks same-integer duplicates.

WU Lifecycle

ready → in_progress → [blocked] → done

Status	Meaning
`ready`	Approved, can be claimed
`in_progress`	Someone is working on it
`blocked`	Waiting on external dependency
`done`	Acceptance met, stamp created

WU Types

wu:create --type accepts seven canonical WU types:

Type	Use it for
`feature`	Net-new user or system capability
`bug`	Broken or regressed behavior fix
`documentation`	Documentation-only change
`process`	Workflow or operating-process maintenance
`tooling`	Tooling, automation, or developer-experience work
`chore`	Repository upkeep or housekeeping
`refactor`	Behavior-preserving code restructure

Two rules matter in practice:

feature WUs require spec_refs. A plan link or spec reference is part of the contract, not an optional note.
documentation and process are the non-code WU types. Use them when the work truly changes docs or operating workflow without touching runtime behavior.

Right-Sizing WUs

WUs should be completable in a single session (<50 tool calls, <30% context). If bigger, split them.

Too Big

❌ “Implement user authentication system”

Right-Sized

✅ “Add login form UI” ✅ “Add password validation” ✅ “Connect login to auth API” ✅ “Add session persistence”

See Sizing Guide for detailed heuristics.

WU vs PR

In LumenFlow:

Traditional	LumenFlow
Create ticket → Code → Open PR → Review → Merge	Create WU → Claim → Code in worktree → Gates → Done

The “review” is automated gates, not human PR review. This unblocks flow while maintaining quality.

Evidence, Not Claims

LumenFlow provides two levels of completion evidence:

Kernel-Level Evidence

Every tool call during a WU’s execution is recorded in the evidence store:

Content-addressed inputs — Tool inputs are hashed with SHA-256 and stored as immutable blobs
Tool traces — TOOL_CALL_STARTED and TOOL_CALL_FINISHED entries with timing, scope enforcement results, and policy decisions
Denial records — Even denied tool calls produce evidence, proving what the agent attempted

WU-Level Evidence

At completion, wu:done creates:

Stamp file in .lumenflow/stamps/WU-XXX.done
Test results proving acceptance criteria
Git history linking to the WU spec

This audit trail answers: What was the agent asked to do? Was the action authorized? What actually happened? See Evidence Store for the full model.

Creating WUs

# With required flags
pnpm wu:create \
  --title "Add password strength meter" \
  --lane "Experience: UI" \
  --type feature \
  --exposure ui \
  --description "Show password strength indicator during registration" \
  --acceptance "Strength meter shows weak/medium/strong" \
  --acceptance "Meter updates in real-time as user types" \
  --code-paths "src/components/PasswordStrength.tsx" \
  --test-paths-unit "src/components/__tests__/password-strength.test.ts" \
  --plan

The command prints the generated ID. The created WU goes into docs/operations/tasks/wu/WU-XXX.yaml with status ready.

Plan-less conversations: If your plan lives in chat or a meeting, keep it lightweight: use --plan to generate a stub at lumenflow://plans/WU-XXX-plan.md, summarize the plan there, and reference it in spec_refs. Feature WUs require spec_refs; notes do not replace the plan link.

Next Steps

Lanes — Organizing work streams with scope boundaries
Gates — Quality enforcement as kernel policies
Evidence Store — The immutable audit trail behind every WU
Kernel Runtime — How WU tasks map to kernel task lifecycle
Sizing Guide — How to size WUs properly