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-id>
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-id>-plan.md

code_paths:
  - src/validation/email.ts

tests:
  unit:
    - src/validation/__tests__/email-validation.test.ts
  manual: []
  e2e: []
  integration: []

exposure: backend-only

artifacts: []

Full WU Schema (Common Fields)

id: <wu-id>
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-id>-plan.md

code_paths:
  - src/example.ts

tests:
  manual:
    - Manual test: Verify behavior
  unit:
    - src/__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-id>
navigation_path: /settings

artifacts: []

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

# Optional lifecycle fields (auto-managed)
claimed_mode: worktree
worktree_path: <path to the WU worktree>
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-id>)
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, waiting, 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  waiting
            ↓      ↓
         in_progress → done

Status	Meaning
ready	Approved, awaiting claim
in_progress	Claimed, being worked on
blocked	Waiting on dependency
waiting	Implementation complete, awaiting sign-off
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[]	human	Human approvers only; wu:claim never writes it (older claims may carry the claimant, which is not an approval)
approved_at	datetime	human	Human approval timestamp; wu:claim never writes it
claim_auto_approval	object	wu:claim	{ agent, at }: the agent auto-approval a claim records. Never a human approval; no gate reads it
requires_human_escalation	boolean	wu:create / wu:edit	Whether a recorded resolution is required at wu:done; a claim never lowers it
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 / wu:edit	Conditions that trigger escalation; a claim merges detected triggers into these and never removes one

Escalation controls are raise-only

escalation_triggers and requires_human_escalation can only be raised once set. wu:claim merges the triggers it detects into the ones already set on the WU (a de-duplicated union) and keeps requires_human_escalation true if it was true. On a ready or claimed WU, raise them with pnpm wu:edit --id WU-XXXX --add-escalation-trigger <trigger> --requires-human-escalation (triggers: sensitive_data, security_p0, budget, cross_lane_arch; the flag is repeatable). A --spec-file edit that tries to drop a trigger or set the flag false is ignored with a warning. An escalation is lowered only by pnpm wu:escalate --id WU-XXXX --resolve (human route; refused in agent sessions, see below), which sets escalation_resolved_by and escalation_resolved_at, records the trigger set it covered in escalation_resolved_triggers (a trigger raised later needs a fresh resolution; older records with no recorded set keep the old behaviour) and escalation_resolution_evidence.

wu:escalate --resolve is a human route and is refused in agent sessions. It needs --approval-id naming a human-escalation approval. approval:request records the requester from the checkout’s git user.email (--requester-id cannot assert another identity), and approval:review records the reviewer. A review is refused when the reviewing process is an agent session. The resolver is always the checkout’s git user.email (--resolver is a cross-check only). The WU records escalation_resolution_evidence (approval id, requester, source, and a sha256 digest binding them to the resolver and time). A request file alone is never accepted. At wu:done the approval is re-verified: it must be approved, for this WU, of type human-escalation, with a user reviewer. A control-plane approval (one posted by approval:request to the control plane, recorded with source: control-plane) is fetched by id through the authenticated control-plane client; an unreachable or missing approval is refused. A local approval record must be present in the checkout where wu:done runs.

Under the trusted policy software_delivery.escalation.mode: delegated, a different agent seat may resolve with pnpm wu:escalate --id WU-XXXX --resolve --delegated: escalation_resolved_by is then delegated-agent:<session> and escalation_resolution_evidence carries resolver_type: delegated-agent with the resolving and claim-holder sessions, the policy digests, the conditions the policy required, the tip SHA and the review and gate references. Under mode: off the gate never refuses and the landed WU carries escalation_advisory (mode, policy digest, triggers). See Escalation modes.

Editing approved_by does not satisfy the wu:done gate. Triggers added with --add-escalation-trigger are recorded in escalation_owner_triggers, which diff evidence never clears. The claiming agent is recorded in claim_auto_approval, which is not a human approval.