Working with Work Items

Work Items track durable units of work from inception to completion, including scope, lifecycle state, acceptance criteria, references, dependencies, and durable notes. Round-by-round execution trace belongs in local loop state and round artifacts.

See also: Tags, TUI, Canonical Edit

Creating Work Items

# Create in queue (pending)
govctl work new "Implement caching layer"

# Create and activate immediately
govctl work new --active "Urgent bug fix"

Work items are automatically assigned IDs like WI-2026-01-17-001.

Work Item Structure

Work items are TOML files with #:schema headers:

#:schema ../schema/work.schema.json

[govctl]
id = "WI-2026-01-17-001"
title = "Implement caching layer"
status = "active"
started = "2026-01-17"
refs = ["RFC-0010", "ADR-0003"]
depends_on = ["WI-2026-01-16-001"]

[content]
description = "Add Redis caching for the query endpoint."
notes = ["Do not retry the old validation path"]

[[content.acceptance_criteria]]
text = "Cache invalidation on write"
status = "pending"
category = "added"

[[content.acceptance_criteria]]
text = "govctl check passes"
status = "pending"
category = "chore"

Work items contain:

• Title — Brief description
• Description — Task scope declaration
• Notes — Durable learnings and constraints
• Acceptance Criteria — Checkable completion criteria with changelog category
• Refs — Links to related RFCs, ADRs, or external resources
• Depends On — Blocking dependencies on other work items

Status Lifecycle

queue → active → done
    ↘        ↘ cancelled

Move Between States

# By ID
govctl work move WI-2026-01-17-001 active
govctl work move WI-2026-01-17-001 done

# By filename (without path)
govctl work move implement-caching.toml active

Moving to done requires all verification guards to pass (see Validation).

Acceptance Criteria

Add Criteria

govctl work add WI-2026-01-17-001 acceptance_criteria "chore: Unit tests pass"
govctl work add WI-2026-01-17-001 acceptance_criteria "add: Documentation updated"

Category prefixes (add:, fix:, change:, chore:, etc.) are required and drive changelog generation. Conventional-commit aliases like feat:, refactor:, test:, docs: are also accepted.

Canonical changelog categories are still the preferred form in stored artifacts. The conventional-commit aliases are accepted as input sugar and normalized into the changelog model.

Mark Criteria Complete

govctl work tick WI-2026-01-17-001 acceptance_criteria "Unit tests" -s done

The pattern matches case-insensitively by substring.

Canonical Edit Paths

Most work item fields are accessible through the unified path-based edit interface. Lifecycle-managed fields (such as status) are excluded — use govctl work move for status transitions instead.

# Set scalar fields
govctl work edit WI-2026-01-17-001 content.description --stdin <<'EOF'
New description here
EOF

# Add to array fields
govctl work edit WI-2026-01-17-001 refs --add RFC-0010
govctl work edit WI-2026-01-17-001 depends_on --add WI-2026-01-16-001
govctl work edit WI-2026-01-17-001 acceptance_criteria --add "fix: Handle edge case"

# Remove by index
govctl work edit WI-2026-01-17-001 content.acceptance_criteria[0] --remove

# Tick checklist items
govctl work edit WI-2026-01-17-001 content.acceptance_criteria[0] --tick done
govctl work edit WI-2026-01-17-001 content.acceptance_criteria[1] --tick cancelled

Path aliases are available for common fields:

Dependencies and Execution Loops

Use depends_on for hard execution ordering between work items. Keep refs for informational links to RFCs, ADRs, clauses, guards, or related work.

govctl work edit WI-2026-01-17-002 depends_on --add WI-2026-01-17-001
govctl check

govctl check validates dependency targets and rejects dependency cycles. A work item should only depend on another work item when the dependent work cannot start until the blocker has completed.

For a batch with multiple independently meaningful work items, create one local execution loop and let govctl generate the loop ID:

govctl loop list open
govctl loop start WI-2026-01-17-001 WI-2026-01-17-002
govctl loop run <LOOP-ID>

Loop state and round evidence live under .govctl/loops/<LOOP-ID>/. loop run opens or validates local rounds; it does not implement code, tick acceptance criteria, add notes, or move work items to done.

When batch scope changes, keep the same loop identity:

govctl loop add <LOOP-ID> work WI-2026-01-17-003
govctl loop remove <LOOP-ID> work WI-2026-01-17-002
govctl loop replan <LOOP-ID>

Use work item notes only for durable lessons or constraints. Put transient execution trace, failed attempts, blockers, next actions, and round summaries in loop state and round artifacts.

Tagging Work Items

Once tags are registered in the project vocabulary, apply them to work items:

govctl work edit WI-2026-01-17-001 tags --add backend
govctl work edit WI-2026-01-17-001 tags --add performance

Filter lists by tag:

govctl work list --tag backend
govctl work list --tag backend,performance

Per-Work-Item Guards

Work items can require extra verification guards in addition to the project’s default guard set.

Example:

[verification]
required_guards = ["GUARD-CLIPPY"]

This means:

• GUARD-CLIPPY is required for this work item even if it is not a project default
• project defaults from gov/config.toml still apply when verification is enabled
• the work item cannot move to done until the effective required guards pass or are explicitly waived

To run the effective guard set for a single work item:

govctl verify --work WI-2026-01-17-001

Waiving A Guard

If a specific guard must be waived for this work item, record that in the artifact with a reason:

[[verification.waivers]]
guard = "GUARD-CARGO-TEST"
reason = "Temporarily flaky on macOS runners; tracked in issue #123"

Waivers are per-work-item only. They do not disable the guard globally, and they should remain rare and justified.

Notes

Add closure-worthy durable notes for constraints or retry rules that should remain useful after the work item is done:

govctl work add WI-2026-01-17-001 notes "Do not retry the old validation path; it fails on missing refs"

Do not use notes for progress updates, commands run, validation output, current plans, next actions, temporary blockers, or TODOs. Put transient execution trace in local loop state and round artifacts instead.

Nested path edits are also available for structured fields:

govctl work edit WI-2026-01-17-001 "content.acceptance_criteria[0].category" --set fixed

Removing Items

Remove items from array fields using flexible matching:

# Substring match (default, case-insensitive)
govctl work remove WI-2026-01-17-001 notes "edge case"

# Exact match
govctl work remove WI-2026-01-17-001 notes "Discovered edge case in validation" --exact

# By index (0-based)
govctl work remove WI-2026-01-17-001 notes --at 0

# Negative index (from end)
govctl work remove WI-2026-01-17-001 notes --at -1

# Regex pattern
govctl work remove WI-2026-01-17-001 refs "RFC-.*" --regex

# Remove all matches
govctl work remove WI-2026-01-17-001 refs "obsolete" --all

Deleting Work Items

Accidentally created work items can be deleted if they’re still in queue status:

govctl work delete WI-2026-01-17-999 -f

Safety: Deletion is only allowed when:

• The work item status is queue (never activated)
• No other artifacts reference it

For work items that have been activated, use status transitions instead:

govctl work move WI-2026-01-17-001 cancelled

Listing and Viewing

govctl work list
govctl work list queue      # Pending items
govctl work list active     # In progress
govctl work list done       # Completed
govctl work show WI-2026-01-17-001  # Styled markdown to stdout