# Spec Status Dashboard

**Completed**: 2026-01-16
**Branch**: 032-status-dashboard
**Feature**: Spec Status Dashboard (`doit status` command)

## Overview

The `doit status` command provides a comprehensive dashboard view of all specifications in a doit project. It displays spec names, statuses, validation results, and identifies commit-blocking issues, helping developers quickly understand project state and readiness.

## Requirements Implemented

| ID | Description | Status |
|----|-------------|--------|
| FR-001 | Scan specs/ directory for all specification files | Done |
| FR-002 | Display each spec's name (derived from directory name) | Done |
| FR-003 | Display each spec's status (Draft, In Progress, Complete, Approved) | Done |
| FR-004 | Display each spec's last modified timestamp | Done |
| FR-005 | Display summary row with total counts by status | Done |
| FR-006 | Run validation checks on each spec | Done |
| FR-007 | Indicate validation pass/fail status for each spec | Done |
| FR-008 | Mark specs that would block commits as "Blocking" | Done |
| FR-009 | Display "Ready to commit" when no blocking issues exist | Done |
| FR-010 | Show validation error count per spec | Done |
| FR-011 | Support `--status <status>` flag to filter by spec status | Done |
| FR-012 | Support `--blocking` flag to show only blocking specs | Done |
| FR-013 | Support `--verbose` flag for detailed validation errors | Done |
| FR-014 | Support `--recent <days>` flag to filter by modification date | Done |
| FR-015 | Default to rich terminal output with colors and formatting | Done |
| FR-016 | Support `--format json` for machine-readable JSON output | Done |
| FR-017 | Support `--format markdown` for documentation-ready output | Done |
| FR-018 | Support `--output <file>` to write report to a file | Done |
| FR-019 | Display helpful error when run outside a doit project | Done |
| FR-020 | Gracefully handle corrupted or unparseable spec files | Done |
| FR-021 | Continue processing remaining specs when one fails to parse | Done |

## Technical Details

### Architecture

- **CLI Layer**: `status_command.py` - Typer-based command with all filtering/output options
- **Service Layer**:
  - `SpecScanner` - Discovers specs, parses status, integrates validation
  - `StatusReporter` - Generates reports with filtering capabilities
- **Formatter Layer**:
  - `RichFormatter` - Rich terminal tables with colors
  - `JsonFormatter` - Machine-readable JSON output
  - `MarkdownFormatter` - GitHub-flavored markdown tables

### Key Decisions

1. **Lazy validation loading** - ValidationService imported only when needed to avoid circular dependencies
2. **Exit codes** - 0 for ready, 1 for blocking specs, 2 for errors (informational, not error)
3. **Blocking logic** - IN_PROGRESS specs block on validation failure; DRAFT specs block only when git-staged
4. **Raw output for JSON/Markdown** - Uses `print()` instead of `console.print()` to avoid ANSI codes

## Files Changed

### New Files
- `src/doit_cli/formatters/__init__.py` - Formatter package exports
- `src/doit_cli/formatters/base.py` - StatusFormatter abstract base class
- `src/doit_cli/formatters/rich_formatter.py` - Rich terminal output
- `src/doit_cli/formatters/json_formatter.py` - JSON output
- `src/doit_cli/formatters/markdown_formatter.py` - Markdown output
- `src/doit_cli/models/status_models.py` - SpecState, SpecStatus, StatusReport
- `src/doit_cli/services/spec_scanner.py` - Spec discovery and parsing
- `src/doit_cli/services/status_reporter.py` - Report generation with filters
- `src/doit_cli/cli/status_command.py` - CLI command implementation
- `tests/unit/test_spec_scanner.py` - 33 unit tests
- `tests/unit/test_status_reporter.py` - 19 unit tests
- `tests/unit/test_formatters.py` - 19 unit tests
- `tests/integration/test_status_command.py` - 13 integration tests

### Modified Files
- `src/doit_cli/main.py` - Registered status command
- `src/doit_cli/models/__init__.py` - Added status model exports
- `src/doit_cli/services/__init__.py` - Added StatusReporter export

## Testing

- **Unit tests**: 71 tests covering SpecScanner, StatusReporter, and all formatters
- **Integration tests**: 13 end-to-end tests covering CLI scenarios
- **Total**: 84 tests, all passing

## Usage Examples

```bash
# Basic status display
doit status

# Filter by status
doit status --status draft
doit status --status complete

# Show only blocking specs
doit status --blocking

# Show detailed validation errors
doit status --verbose

# Filter by recent modifications
doit status --recent 7

# JSON output
doit status --format json

# Markdown output
doit status --format markdown

# Save to file
doit status --format json --output report.json
```

---
Generated by `/doit.checkin`
