ticket: clarify WorkItem model

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<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.

work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md

@@ -0,0 +1,66 @@
+---
+id: 20260601-031252-builtin-work-item-intake-routing
+slug: builtin-work-item-intake-routing
+title: Built-in work item management and intake routing
+status: open
+kind: task
+priority: P1
+labels: [work-item, intake, orchestration, tui]
+created_at: 2026-06-01T03:12:52Z
+updated_at: 2026-06-01T05:26:27Z
+assignee: null
+legacy_ticket: null
+---
+
+## Issue
+
+現在の work item / ticket 運用は、Insomnia システムから切り離しても使えるように `tickets.sh` と markdown files で管理している。一方で、チケットは実質的に WorkItem と統合された構造化データとして運用され始めており、Intake Pod / Orchestrator / coder / reviewer の並行開発フローでは、チケット管理自体を Insomnia の feature として扱う必要が出てきている。
+
+特に、ユーザーが単一 Orchestrator に依頼してから Orchestrator が調査・チケット化・実装委譲する現在の入口では、ユーザー待ち時間が残る。ユーザーの submit から Intake Pod が直接起動し、ユーザーと意図・要件をすり合わせたうえで正式な WorkItem / ticket を作成し、Orchestrator はそのチケット群の順序付け・割り込み・実装 orchestration に集中する構造へ移行したい。
+
+## Direction
+
+- `tickets.sh` 相当の work item 管理を、Insomnia の built-in feature / tool surface として設計・実装する。
+- Intake Pod はユーザーと直接会話し、必要な調査・重複確認・要件同期を行い、合意済み WorkItem / ticket を作成できるようにする。
+- Orchestrator はユーザー意図の一次解釈や ticket draft の再承認者ではなく、登録済み WorkItem の scheduling / prioritization / interruption / implementation delegation を担当する。
+- ユーザー向け Inbox 専用 UI は初期スコープにしない。Intake は既存の `--multi` UI の延長として通常の Pod 会話で制御できるようにする。
+- Orchestrator が WorkItem を見て不十分と判断し、Intake と Orchestrator 間だけで合意できない場合は、Intake Pod に action-required flag を持たせ、既存の TUI polling / multi-Pod 表示経路でユーザー対応要求として表示する。
+
+## Scope / permission note
+
+Scope は、エージェントが占有して作業する filesystem space を保証するための仕組みである。WorkItem / ticket 管理を built-in tool として提供する場合、その tool は単なる delegated workspace edit と同じ扱いにせず、既存の `tickets.sh` / Bash と同様に work item authority のための専用経路として設計してよい。
+
+ただし、これは無制限のファイル編集許可を意味しない。WorkItem tool は対象を work item store に限定し、通常の code/worktree scope とは別の authority boundary と auditability を持つべきである。
+
+## Requirements
+
+- `tickets.sh` で行っている主要操作を、Insomnia の built-in work item management surface として扱えるようにすること。
+  - create
+  - show/list
+  - comment / plan / decision / implementation report
+  - review approve/request-changes
+  - status transition
+  - close / resolution
+  - doctor / consistency check
+- WorkItem / ticket の保存形式は、現在の markdown + frontmatter + thread / artifacts 方式との移行可能性を保つこと。
+- 既存の `tickets.sh` 運用を即座に破壊しないこと。built-in 化の途中でも git history / work-items directory を authority として読めること。
+- Intake Pod がユーザーと合意済み WorkItem を作成できる導線を設計すること。
+- Intake Pod は正式作成前に、必要に応じて既存 ticket / duplicate / related work / relevant files を調査できること。
+- Intake Pod が作った WorkItem には、ユーザー合意済みであること、背景、要件、acceptance criteria、non-goals、risk flags、needs-preflight などを構造化して残せること。
+- Orchestrator は作成済み WorkItem queue を見て、実装順序・割り込み・preflight 要否・coder/reviewer 起動を判断できること。
+- Orchestrator が WorkItem 不十分と判断した場合、必要な質問や修正要求を Intake Pod 経由でユーザーに戻せること。
+- 専用 Inbox storage / UI を初期要件にしないこと。action-required state は Pod metadata / current state に近い形で持ち、既存 multi-Pod polling / display で見えるようにすること。
+- action-required Pod は、ユーザーが対応するまで見落とされにくい表示・状態を持つこと。
+- Intake 結果や WorkItem 操作は audit 可能で、git history / work item thread に経緯が残ること。
+- secret / private context を WorkItem 本文・thread・artifact・diagnostics に不用意に書かないこと。
+- work item store への並行書き込みが壊れないよう、atomicity / locking / conflict handling を設計すること。
+
+## Acceptance criteria
+
+- Insomnia 内部から、少なくとも `tickets.sh create/show/list/comment/review/close/doctor` に相当する操作を型付きに実行できる。
+- Intake Pod がユーザーと合意した内容を正式 WorkItem として作成できる。
+- Orchestrator は Intake が作成した WorkItem を、再解釈 gate なしに scheduling 対象として扱える。
+- WorkItem が不十分な場合は、Orchestrator が action-required state を通じて Intake / user に差し戻せる。
+- `--multi` 系 UI で、通常の Pod 状態に加えて user action required な Intake Pod を認識できる。
+- 専用 Inbox storage を導入しなくても、未対応のユーザー確認要求が見落とされない。
+- 既存 `work-items/` と git history に基づく運用・監査が継続できる。

work-items/open/20260601-031252-builtin-work-item-intake-routing/thread.md

@@ -0,0 +1,233 @@
+<!-- event: create author: tickets.sh at: 2026-06-01T03:12:52Z -->
+
+## Created
+
+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.
+
+
+---