---
_version: '1'
uuid: dfd8a39a-c6bb-4675-81af-2de70685f219
created: 2025-10-27T12:00:00Z
parents:
- uuid: f86dfe3c-ceb9-4e28-bbb4-66588076f2b2
fingerprint: 2c908e949aafeefdeee65f572508e0ac429aa6fafc956c36bcc9c479b03779f8
hrid: SYS-009
- uuid: 96bcbcca-a8e4-450f-bdaa-0f23c93e1a36
fingerprint: 34e04ddb515030e490922d8d7a64a04cb5495954bc44d460310ce6c37a5ecd46
hrid: SYS-008
- uuid: d1b46364-2297-409c-9bbe-8b0134cf86e6
fingerprint: 45352c3d0c3192db4c7514b1182eea4220ad39661603c0983a9c7dc250d8a28e
hrid: SYS-010
---
# SPC-001 Suspect Link Remediation CLI Specification
## Purpose
Provide a cohesive terminal experience that helps engineers notice, inspect, and resolve suspect links with confidence, whether they are investigating a single change or sweeping a backlog after a review cycle.
## Experience Principles
- **Clarity first:** Highlight child → parent relationships in a consistent, column-aligned layout with subtle colour (when available) and unambiguous labels.
- **Progressive disclosure:** Offer terse summaries by default, then reveal fingerprints or paths only when users request extra context.
- **Guardrails:** Make irreversible actions deliberate through confirmations, dry-runs, and exit codes that play well with automation.
- **Speed:** Ensure commands feel instantaneous on the happy path (no unnecessary prompts, minimal chatter).
## Command Behaviours
### `req suspect`
- Default output is a compact table: `CHILD PARENT STATUS`, sorted by child HRID. The `STATUS` column shows a short diagnosis (`fingerprint drift`, `parent missing`, etc.).
- `--detail` expands each row into a block that adds stored vs. current fingerprints plus the parent file path. Blocks are separated by thin dashed rules for scanability.
- `--format json|ndjson` mirrors the table data. JSON keys: `child`, `parent`, `status`, `stored_fingerprint`, `current_fingerprint`, `child_path`, `parent_path`.
- When no suspect links remain, print `✅ No suspect links detected.` and exit with `0`.
- When suspect links exist, exit with `2` and keep stderr quiet so table output is script-friendly.
### `req accept <child> <parent>`
- Before writing, present a confirmation banner summarising the link:
```
Reviewing: CHILD → PARENT
Stored: <hash>
Current: <hash>
```
- Prompt: `Accept this link? (y/N)` with uppercase default to reduce accidental confirmation. `--yes` skips the prompt.
- On success, print `Accepted CHILD ← PARENT` in green (fallback to plain text when colours are disabled).
- If the link is not suspect, warn: `No changes: link already up-to-date.` and exit with `0`.
- Unknown relationships fail with exit code `64` (usage error) and message `Unable to find parent PARENT for child CHILD`.
### `req accept --all`
- Always begin with a dry-run preview when no explicit mode is chosen. Show a summary table:
```
Pending updates: 24 suspect links
Use --apply to write changes.
```
- Flags:
- `--dry-run` (default) prints the list and exits `0`.
- `--apply` performs the write path.
- `--yes` (or `--force`) skips the confirmation prompt that appears before writing.
- Confirmation copy: `Apply updates to 24 suspect links across 10 files? (y/N)`
- During apply, stream progress as `Updating CHILD ← PARENT`. On completion, show a compact recap (`Links updated: 24 | Files touched: 10 | Duration: 0.9s`).
- Exit codes: `0` on success, `2` if suspect links remain after the command (e.g., when run in dry-run mode), `70` for IO failures.
## Accessibility & Ergonomics
- Follow no-colour environment variables (`NO_COLOR`, `CLICOLOR=0`) and provide readable monochrome output.
- Table layouts use spaces, not tabs, so alignment is predictable across shells.
- Prompts treat EOF (Ctrl-D) as “cancel” and exit with code `130`, mirroring interrupted commands.
- Messages avoid gendered language, use sentence case, and keep line width ≤ 80 characters.
## Empty-State & Error Messaging
- Empty preview (`req accept --all --dry-run` with nothing to do) returns: `Nothing to update. All suspect links are already accepted.` plus exit `0`.
- If the graph cannot be loaded, display `Unable to read requirements. See logs above.` and exit `70`.
- Validation errors refer to HRIDs, not internal UUIDs, so engineers can locate files quickly.