<!--
agentCapsule|v=1|command=list-tasks|module=task-engine|schema_only=pnpm exec wk run list-tasks --schema-only '{}'
-->

# list-tasks

List tasks from the Task Engine store with optional filters.

## Usage

```
workspace-kit run list-tasks '{}'
workspace-kit run list-tasks '{"status":"ready"}'
workspace-kit run list-tasks '{"phase":"Phase 1 task engine core"}'
workspace-kit run list-tasks '{"type":"improvement","category":"reliability","tags":["ui","sqlite"]}'
workspace-kit run list-tasks '{"metadataFilters":{"owner.team":"platform","risk.level":"high"}}'
workspace-kit run list-tasks '{"phaseKey":"28","status":"ready"}'
workspace-kit run list-tasks '{"includeQueueHints":true,"status":"ready"}'
workspace-kit run list-tasks '{"includeTaskIntake":true,"status":"proposed","limit":20}'
workspace-kit run list-tasks '{"type":"improvement","confidenceTier":"medium"}'
workspace-kit run list-tasks '{"status":"blocked","blockedReasonCategory":"external_dependency"}'
workspace-kit run list-tasks '{"features":["doc-generation"]}'
workspace-kit run list-tasks '{"featureId":"doc-generation"}'
workspace-kit run list-tasks '{"componentId":"cli-modules-agent-surfaces"}'
```

## Arguments

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Filter by task status |
| `phase` | string | no | Filter by exact `task.phase` string |
| `phaseKey` | string | no | Filter by stable phase key (`task.phaseKey` or inferred from `task.phase`, e.g. `28`) |
| `features` | string or string[] | no | Filter by feature taxonomy slug(s): **OR** semantics — task matches if `task.features` includes **any** listed slug |
| `featureId` | string | no | Single slug filter: task must list this feature (requires relational registry / `user_version` 5+ for consistent junction reads) |
| `componentId` | string | no | Filter tasks that have **any** feature belonging to this component id (slugified category id from registry; `user_version` 5+) |
| `type` | string | no | Filter by task type (for example `improvement`) |
| `category` | string | no | Filter by `metadata.category` |
| `tags` | string or string[] | no | Filter by `metadata.tags` (all tags must match) |
| `metadataFilters` | object | no | Safe metadata path filters; keys must match `segment(.segment)*` |
| `confidenceTier` | string | no | Filter improvement (or any task) by `metadata.confidenceTier` (`high` / `medium` / `low`) |
| `blockedReasonCategory` | string | no | Filter by `metadata.blockedReasonCategory` (v1 taxonomy: `human_review`, `external_dependency`, `scope_unclear`) |
| `includeArchived` | boolean | no | Include archived tasks when `true` |
| `includeQueueHints` | boolean | no | When `true`, adds `queueHintRows` (same order as `tasks`) with `phaseAligned`, `blockedByDependencies`, `unmetDependencies` |
| `includeTaskIntake` | boolean | no | When `true`, adds `taskIntakeByTaskId` keyed by task id with compact resolved intake (accept→ready triage) for each row in the page — requires effective workspace config; read-only |

## Returns

Object with `tasks`, `count`, and `scope`. Each task row preserves the stored task fields and also includes stable read-model projections for `priority`, `severity`, `components`, and feature taxonomy `features` (empty arrays / `null` when absent). When `includeQueueHints` is true, `queueHintRows` is included. When `includeTaskIntake` is true, `taskIntakeByTaskId` is included.
