ADR-0019: Change -n from dry-run to limit for better Unix convention alignment

Status: accepted | Date: 2026-01-19

References: ADR-0006, ADR-0017

Context

ADR-0006 and ADR-0017 assigned -n as the short flag for --dry-run, following rsync’s convention. However, this conflicts with the more universal Unix convention where -n means “number” or “limit”:

Standard Unix tools using -n for number/limit:

• head -n 10 (limit to N lines)
• tail -n 10 (limit to N lines)
• grep -n (show line numbers)
• sort -n (numeric sort)
• ls -n (numeric IDs)

Tools using -n for dry-run:

• rsync -n (dry-run) - notable exception
• Very few other standard tools

Current problem: We need to add --limit flag to all list commands to control result count. The natural short flag would be -n, but it’s already taken by dry-run. This forces us to either:

1. Use no short flag for limit (verbose, less ergonomic)
2. Change -n to mean limit (breaks ADR-0006/ADR-0017)

Impact of current design:

• govctl work list --limit 5 is verbose (no short option)
• Inconsistent with head -n 5 / tail -n 5 muscle memory
• Dry-run is a safety flag (verbose is acceptable)
• Limit is used frequently in interactive sessions (short flag valuable)

Decision

Reassign -n from dry-run to limit:

1. Remove -n short flag from --dry-run (keep long form only)

   • Dry-run remains accessible as --dry-run
   • This is a safety flag - verbosity is appropriate

2. Add -n short flag to --limit on all list commands

   • govctl rfc list -n 10
   • govctl work list -n 5
   • Aligns with head -n / tail -n conventions

3. Amend ADR-0006 and ADR-0017 to reflect this change

Rationale:

• Unix convention alignment: -n for “number” is far more common
• Ergonomics: Limit is used frequently, dry-run less so
• Safety: Dry-run benefits from being explicit (--dry-run)
• Pre-1.0 window: Breaking changes are acceptable now
• Consistency: Follows head/tail patterns users know

Consequences

Positive:

• Natural -n for limit matches Unix expectations
• More ergonomic interactive use: govctl work list -n 5
• Explicit --dry-run is clearer for safety-critical flag
• Consistent with standard tooling (head, tail, etc.)

Negative:

• Breaking change: Scripts using -n for dry-run will break
• Requires updating ADR-0006 and ADR-0017
• Requires updating any documentation mentioning -n

Migration:

• All uses of -n must change to --dry-run
• Update .claude/CLAUDE.md and other docs
• Add to CHANGELOG as breaking change
• Search codebase for any hardcoded -n usage

Affected ADRs:

• ADR-0006: Originally defined -n for dry-run
• ADR-0017: Documents -n as global dry-run flag