# WorkItem definition and API shape

> Superseded on 2026-06-05: the durable orchestration record concept is now named `Ticket`, not `WorkItem`. See `ticket-definition-and-api-shape-20260605.md` and the ticket thread decision for current terminology. This file is retained as historical design context.

## Definition

In Insomnia, a WorkItem is not primarily an issue tracker item. A WorkItem is an agreed execution contract that fixes user intent into a bounded unit that Pods can schedule, delegate, implement, review, and close safely.

Short definition:

> A WorkItem is a durable work contract that preserves user/system-agreed intent and gives Pod groups enough boundary, readiness, and evidence to execute, verify, and complete the work without degrading the original intent.

A ticket file, GitHub Issue, Linear issue, Jira issue, or another tracker record can be a persistence representation of a WorkItem, but none of those representations define the concept itself.

## Roles served by a WorkItem

A WorkItem is simultaneously:

- Intent anchor: preserves what the user and Intake agreed to.
- Delegation packet: lets Orchestrator/Coder understand what should be done and where to stop.
- Review contract: gives Reviewer an explicit basis for approval or request-changes.
- Scheduling unit: lets Orchestrator prioritize, interrupt, parallelize, and assign work.
- Boundary: records scope, non-goals, authority limits, privacy constraints, and escalation conditions.
- Lifecycle record: records plans, decisions, implementation reports, reviews, commits, validation, and resolution.

## Relationship to tickets and issue trackers

- WorkItem is the Insomnia orchestration concept.
- Local markdown ticket is one backend representation.
- GitHub/Linear/Jira issue is another possible backend representation.
- The backend should be abstracted below the WorkItem API.

The WorkItem abstraction should not try to become a complete issue tracker abstraction. It should cover only the subset needed for Insomnia orchestration: create/list/show, structured lifecycle events, status/readiness, review, close, consistency checks, and references/evidence.

## Typing strategy

Use a thin typed envelope with rich Markdown/freeform bodies and events.

The API should type fields that the system reads mechanically, while leaving the content that carries human intent as Markdown/freeform text. This keeps compatibility with external issue trackers and avoids turning Intake into a rigid form-filling flow.

### Typed fields

These should be typed because Orchestrator, TUI, policy, or tools branch on them:

- Identity:
  - backend id
  - external/work item id
- Classification:
  - kind
  - priority
  - labels as free strings
- State:
  - canonical status
  - readiness
  - action-required state
  - needs-preflight flag
  - risk flags
- Lifecycle operation/event kind:
  - comment
  - plan
  - decision
  - implementation report
  - review approved
  - review request-changes
  - status changed
  - closed
- References:
  - related WorkItems
  - files
  - branches
  - commits
  - Pods
  - URLs/artifacts
- Backend capability metadata:
  - create/comment/review/close support
  - artifact support
  - offline support
  - transactional/local-git support

Enums should not be closed too tightly. Use escape hatches such as `Other(String)` or canonical+raw mappings for tracker compatibility.

Examples:

```rust
enum WorkItemKind {
    Bug,
    Task,
    Feature,
    Design,
    Chore,
    Other(String),
}

struct MappedStatus {
    canonical: WorkItemStatus,
    raw: Option<String>,
}
```

### Freeform / Markdown fields

These should remain Markdown/freeform because AI agents and humans can read them well and external trackers can round-trip them:

- issue / problem statement
- user intent
- background / rationale
- requirements
- acceptance criteria
- non-goals
- invariants
- escalation conditions
- investigation notes
- implementation reports
- review comments
- resolution details

The event kind should be typed, but event body should remain Markdown.

```rust
struct WorkItemEvent {
    kind: WorkItemEventKind,
    body: MarkdownText,
    refs: Vec<WorkItemRef>,
}
```

## Suggested initial model

```rust
struct WorkItem {
    id: WorkItemId,
    title: String,
    classification: WorkItemClassification,
    state: WorkItemState,
    body: WorkItemDocument,
    events: Vec<WorkItemEvent>,
    refs: Vec<WorkItemRef>,
    backend: BackendMetadata,
    extensions: serde_json::Map<String, serde_json::Value>,
}
```

```rust
struct WorkItemState {
    status: MappedStatus,
    readiness: Readiness,
    action_required: Option<ActionRequired>,
    needs_preflight: bool,
    risk_flags: Vec<RiskFlag>,
}
```

```rust
struct WorkItemDocument {
    issue: MarkdownText,
    requirements: MarkdownText,
    acceptance_criteria: MarkdownText,
    non_goals: Option<MarkdownText>,
    notes: Option<MarkdownText>,
}
```

## API principle

Operations should be typed; payload bodies should be flexible.

Examples:

- `CreateWorkItem(NewWorkItem)` is typed.
- `AddWorkItemEvent { kind, body }` is typed by operation/event kind, freeform in body.
- `UpdateWorkItemState { readiness, action_required, risk_flags }` is typed.
- `CloseWorkItem { resolution: MarkdownText }` has typed operation semantics and freeform resolution text.

This gives enough structure for audit, scheduling, TUI display, and automation, without forcing issue-tracker-specific fields into the core model.

## Lint over hard schema

Prefer a WorkItem linter/policy layer over strict structural enforcement for body content.

Examples:

- title must be present.
- issue/requirements should not be empty.
- P0/P1 items without acceptance criteria should warn.
- risk flags with `needs_preflight = false` should warn.
- secret-like literals should warn or fail depending on policy.
- closing without review/resolution can warn or fail depending on project policy.

This makes the system agent-friendly and backend-compatible while still catching low-quality WorkItems.

## Backend abstraction

Backends should implement WorkItem storage/sync, not redefine WorkItem semantics.

```text
Intake / Orchestrator / TUI / Workflows
        ↓
    WorkItem API
        ↓
WorkItemBackend
   ├─ LocalFilesBackend
   ├─ GitHubIssuesBackend
   ├─ LinearBackend
   ├─ JiraBackend
   └─ MCPWorkItemBackend
```

Each backend should expose capabilities. The tool/TUI surface should show only operations supported by the configured backend.

## Scope and authority

WorkItem tool authority is separate from normal code/worktree filesystem scope.

Filesystem scope protects exclusive editing of implementation areas. WorkItem management is shared project coordination state and should be mediated by typed WorkItem operations, backend locks/conflict handling, and audit records rather than ordinary delegated write scope.

This does not imply unlimited file access. The WorkItem tool should be limited to configured WorkItem backends and operations.

## Design consequence

The first implementation can be LocalFilesBackend over current `work-items/`, preserving markdown/frontmatter/thread/artifacts and `tickets.sh` compatibility. The API should already be backend-shaped so GitHub Issues or other trackers can be added later without changing Intake/Orchestrator semantics.
