---
_version: '1'
uuid: 30e19e3f-db38-427f-8f23-98f15ae94816
created: 2025-10-27T12:10:00Z
parents:
- uuid: cdc17618-c093-47d4-a145-a216b32fd866
fingerprint: 78571a414810ffa9175db579104b86aba03beeebe1f64abd3e0a0bde9472a8a4
hrid: SYS-020
---
# SPC-003 Status Dashboard CLI Specification
## Purpose
Deliver an at-a-glance health report that fits in a single terminal viewport, gives teams confidence before merges, and doubles as a CI gate when traceability drifts.
## Layout
```
req status
Requirement counts
──────────────────
Kind Count Δ
USR 12 +1
SYS 20 0
TST 5 -1
Total 37
Suspect links: 3 ⚠️
```
- Section headers use sentence case and a thin horizontal rule beneath them.
- The delta column (`Δ`) shows the change relative to the most recent git commit when available; fallback is `–`.
- Colour accents:
- Positive delta → green `+`.
- Negative delta → amber `-`.
- Zero delta → dimmed `0`.
- When no suspect links remain, render `Suspect links: 0 ✅`. When they exist, surface a prompt: `Run 'req suspect' to investigate.`
## Behaviour
- Default command (`req status`) runs instantly with no prompts and exits `0` when there are zero suspect links, `2` when suspect links exist, and `70` on IO failures.
- `--output json` returns:
```json
{
"kinds": [{"kind":"USR","count":12,"delta":1}, ...],
"total": {"count":37,"delta":0},
"suspect_links": 3
}
```
- `--quiet` prints only the total count and suspect link number on one line (`total=37 suspect=3`).
## Accessibility & Ergonomics
- Detect narrow terminals (<60 columns) and switch to stacked output where each kind is printed as `USR: 12 (Δ +1)`.
- Avoid relying on colour: include symbols (`+`, `-`, `0`, `⚠️`, `✅`) with text alternatives.
- Respect `NO_COLOR` and `CLICOLOR=0` to disable ANSI escapes.
- Keep runtime under 200 ms for repositories under 1k requirements; display a spinner with `Analysing requirements…` if longer.
## Messaging
- On suspect links: `3 suspect links detected. Review with 'req suspect'.`
- On data load issues: `Unable to compute status. See errors above.` (exit `70`).
- When no requirements exist: `No requirements found yet. Create one with 'req add'.` plus exit `0`.