ticket: clarify WorkItem model
This commit is contained in:
parent
dadf3ae7a3
commit
15fb1e5741
|
|
@ -0,0 +1,218 @@
|
|||
# WorkItem definition and API shape
|
||||
|
||||
## 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.
|
||||
|
|
@ -7,7 +7,7 @@ kind: task
|
|||
priority: P1
|
||||
labels: [work-item, intake, orchestration, tui]
|
||||
created_at: 2026-06-01T03:12:52Z
|
||||
updated_at: 2026-06-01T03:12:52Z
|
||||
updated_at: 2026-06-01T05:26:27Z
|
||||
assignee: null
|
||||
legacy_ticket: null
|
||||
---
|
||||
|
|
|
|||
|
|
@ -4,4 +4,230 @@
|
|||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-01T05:26:27Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
# WorkItem definition and API shape
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user