WU Schema

Work Units are defined in YAML files under docs/tasks/wu/ by default. This path is configurable via software_delivery.directories.wuDir in workspace.yaml.

YAML parsing notes

• LumenFlow tooling parses and serializes WU YAML using the yaml library.
• Unquoted YYYY-MM-DD values are treated as strings (no Date coercion).

Minimal (Claim-Ready) WU

id: WU-001
title: Add email validation
lane: Framework: Core
type: feature
status: ready
priority: P2
created: 2026-01-21
assigned_to: engineer@example.com

description: |
  Context: Login accepts invalid emails.
  Problem: Users submit bad addresses and fail later.
  Solution: Add client-side validation with tests.

acceptance:
  - Invalid format shows error on blur
  - Valid email allows submission
  - Unit test covers validation

spec_refs:
  - docs/plans/WU-001-plan.md

code_paths:
  - packages/@lumenflow/core/src/validation/email.ts

tests:
  unit:
    - packages/@lumenflow/core/__tests__/email-validation.test.ts
  manual: []
  e2e: []
  integration: []

exposure: backend-only

artifacts:
  - .lumenflow/stamps/WU-001.done

Full WU Schema (Common Fields)

id: WU-001
title: Add email validation
lane: Framework: Core
type: feature
status: ready
priority: P2
created: 2026-01-21
assigned_to: engineer@example.com

description: |
  Context: ...
  Problem: ...
  Solution: ...

acceptance:
  - Criterion 1
  - Criterion 2

spec_refs:
  - docs/plans/WU-001-plan.md

code_paths:
  - packages/@lumenflow/core/src/example.ts

tests:
  manual:
    - Manual test: Verify behavior
  unit:
    - packages/@lumenflow/core/__tests__/example.test.ts
  e2e: []
  integration: []

exposure: backend-only # ui | api | backend-only | documentation
user_journey: |
  Optional user flow for ui/api exposure.
ui_pairing_wus:
  - WU-1234
navigation_path: /settings

artifacts:
  - .lumenflow/stamps/WU-001.done

dependencies: []
risks:
  - Risk 1
notes: ''
requires_review: false

# Optional lifecycle fields (auto-managed)
claimed_mode: worktree
worktree_path: worktrees/framework-core-wu-001
claimed_at: 2026-01-21T12:00:00Z
completed_at: 2026-01-22T09:00:00Z

Required Fields for New WUs

Field	Type	Description
id	string	Unique identifier (e.g., WU-001)
title	string	Short description
lane	string	Parent: Sublane (e.g., Framework: CLI)
type	enum	feature, bug, documentation, process, tooling, chore, refactor
status	enum	ready, in_progress, blocked, done, cancelled
priority	enum	P0, P1, P2, P3
created	date	YYYY-MM-DD
assigned_to	string	Assignee email
description	string	Context/Problem/Solution
acceptance	string[]	Testable criteria
code_paths	string[]	Required for non-doc WUs
tests	object	At least one test path for non-doc WUs
exposure	enum	ui, api, backend-only, documentation
spec_refs	list	Required for feature WUs
artifacts	list	Usually includes stamp path

Validation

WU specs are validated on:

• wu:create – creation requires a complete spec (no placeholders)
• wu:claim – blocks incomplete specs
• wu:done – enforces completeness and code path validity

Validation checks include:

• Required fields present
• No [PLACEHOLDER] markers
• Code paths and tests for non-doc WUs
• Exposure and spec_refs (feature)
• Schema conformity

Status Lifecycle

ready → in_progress → done
            ↓
         blocked → in_progress → done

Status	Meaning
ready	Approved, awaiting claim
in_progress	Claimed, being worked on
blocked	Waiting on dependency
done	Acceptance met, stamped
cancelled	Dropped/obsolete

Auto-Managed Fields

These fields are set automatically by CLI tooling during the WU lifecycle. Do not set them manually.

Field	Type	Set By	Description
locked	boolean	wu:claim	Whether the WU is locked to a worktree
claimed_mode	string	wu:claim	Claim mode (worktree or branch)
worktree_path	string	wu:claim	Path to the worktree directory
baseline_main_sha	string	wu:claim	Git SHA of main at time of claim
session_id	string	wu:claim	Agent session identifier
approved_by	string[]	wu:done	Approvers list
approved_at	datetime	wu:done	Approval timestamp
requires_human_escalation	boolean	wu:create	Whether human approval is required
requires_cso_approval	boolean	wu:create	CSO approval required
requires_cto_approval	boolean	wu:create	CTO approval required
requires_design_approval	boolean	wu:create	Design approval required
escalation_triggers	string[]	wu:create	Conditions that trigger escalation