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

# phase-status

Read the canonical workspace phase, drift hints, export freshness, and optional task counts in one JSON payload.

## Usage

```bash
workspace-kit run phase-status '{"includeTaskCounts":true,"includeDriftDetails":true,"includePhaseJournalSummary":true}'
```

## Arguments

| Field | Required | Description |
| --- | --- | --- |
| **`includeTaskCounts`** | No | When **`true`**, include current-phase and next-phase task counts grouped by task status. |
| **`includeDriftDetails`** | No | When **`true`**, include human-readable drift detail strings in addition to remediation commands. |
| **`includePhaseJournalSummary`** | No | When **`true`**, include a bounded **`phaseJournal`** object: kit SQLite user_version reachability, canonical phase key echo, and **`activeCriticalNoteCount`** for active notes in that phase (no note bodies). Omitted when the flag is false/absent. |

## Behavior

This command is read-only. It reads **`kit_workspace_status`** when present, resolves canonical phase with the same precedence as queue health (workspace status first, config only as fallback), reports project config phase hints, checks the non-authoritative DB export freshness by comparing exported **`workspaceRevision`** to the SQLite workspace-status row, and optionally counts tasks by phase bucket. Unrelated task/CAE writes to the planning SQLite file do not make the export stale.

When **`includePhaseJournalSummary`** is true, critical counts use the same passive-expiry visibility rules as **`list-phase-notes`** (expired active rows are excluded unless the journal store treats them as still listed; the summary uses the phase journal list helper with **`includeExpired: false`**).

Workspace current phase and task **`phaseKey`** are separate concepts. Task counts use each task’s explicit **`phaseKey`** or inferred **`phase`** label, and the command never changes task rows.

## Response

Returns:

- **`workspaceStatus`**, **`currentKitPhase`**, and **`nextKitPhase`** from SQLite when available.
- **`canonicalPhase`** with source, config phase key, workspace-status phase key, and config-vs-SQLite match status.
- **`configHint`** for **`kit.currentPhaseNumber`** / **`kit.currentPhaseLabel`**.
- **`exportStatus`** for **`docs/maintainers/data/workspace-kit-status.db-export.yaml`**, including **`workspaceRevision`** and **`exportWorkspaceRevision`** when the export marker is present.
- **`remediationSuggestions`** when config or export drift is detected.
- **`taskCounts`** when requested.
- **`phaseJournal`** when **`includePhaseJournalSummary`** is true: **`supported`**, **`kitSqliteUserVersion`**, **`phaseKey`**, **`activeCriticalNoteCount`** (null when unsupported or phase unknown).

## Examples

Cheap phase read:

```bash
workspace-kit run phase-status '{}'
```

Counts and drift details:

```bash
workspace-kit run phase-status '{"includeTaskCounts":true,"includeDriftDetails":true}'
```

Phase journal observability (counts only):

```bash
workspace-kit run phase-status '{"includePhaseJournalSummary":true}'
```
