diff --git a/work-items/open/20260601-031252-builtin-work-item-intake-routing/artifacts/workitem-definition-and-api-shape-20260601.md b/work-items/open/20260601-031252-builtin-work-item-intake-routing/artifacts/workitem-definition-and-api-shape-20260601.md new file mode 100644 index 00000000..f129e8d8 --- /dev/null +++ b/work-items/open/20260601-031252-builtin-work-item-intake-routing/artifacts/workitem-definition-and-api-shape-20260601.md @@ -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, +} +``` + +### 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, +} +``` + +## Suggested initial model + +```rust +struct WorkItem { + id: WorkItemId, + title: String, + classification: WorkItemClassification, + state: WorkItemState, + body: WorkItemDocument, + events: Vec, + refs: Vec, + backend: BackendMetadata, + extensions: serde_json::Map, +} +``` + +```rust +struct WorkItemState { + status: MappedStatus, + readiness: Readiness, + action_required: Option, + needs_preflight: bool, + risk_flags: Vec, +} +``` + +```rust +struct WorkItemDocument { + issue: MarkdownText, + requirements: MarkdownText, + acceptance_criteria: MarkdownText, + non_goals: Option, + notes: Option, +} +``` + +## 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. diff --git a/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md b/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md index a02a64e4..eafffb1d 100644 --- a/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md +++ b/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md @@ -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 --- diff --git a/work-items/open/20260601-031252-builtin-work-item-intake-routing/thread.md b/work-items/open/20260601-031252-builtin-work-item-intake-routing/thread.md index bab407bf..18f4986b 100644 --- a/work-items/open/20260601-031252-builtin-work-item-intake-routing/thread.md +++ b/work-items/open/20260601-031252-builtin-work-item-intake-routing/thread.md @@ -4,4 +4,230 @@ Created by tickets.sh create. +--- + + + +## 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, +} +``` + +### 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, +} +``` + +## Suggested initial model + +```rust +struct WorkItem { + id: WorkItemId, + title: String, + classification: WorkItemClassification, + state: WorkItemState, + body: WorkItemDocument, + events: Vec, + refs: Vec, + backend: BackendMetadata, + extensions: serde_json::Map, +} +``` + +```rust +struct WorkItemState { + status: MappedStatus, + readiness: Readiness, + action_required: Option, + needs_preflight: bool, + risk_flags: Vec, +} +``` + +```rust +struct WorkItemDocument { + issue: MarkdownText, + requirements: MarkdownText, + acceptance_criteria: MarkdownText, + non_goals: Option, + notes: Option, +} +``` + +## 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. + + ---