Remove shortcut commands that shadow group nouns

Merged
RO
4mo ago
+546-1622

Summary

  • Removes 7 top-level shortcut commands — card, todo, done, reopen, message, comment, react — that either shadowed a plural group noun or duplicated an existing subcommand. Every one has a canonical equivalent (cards create, todos create, todos complete, todos uncomplete, messages create, comments create, boost create; boosts create also works as an alias), so the supported paths remain available.
  • Current diff after rebasing on main: 46 files changed, +555/−1,631 lines (net −1,076). The changes remove shortcut command code and update breadcrumbs, help text, skills/basecamp/SKILL.md examples, STYLE.md, e2e bats, and the .surface / .surface-skill-drift snapshots.
  • STYLE.md now forbids new top-level verbs that shadow a group noun; scripts/check-bare-groups.sh no longer allowlists NewCardCmd.

Why

basecamp card show 9760604112 looked like a read but actually ran card <title> [body] and silently created a malformed card with title show and body 9760604112. Two such cards showed up in BC5 on 2026-04-07 — investigation on card 9768602954 traced the root cause to the singular-noun create shortcuts colliding with the plural-noun read commands. Agents were the most likely mistaken caller, but any user could hit it the same way.

The canonical <group> <verb> paths are what SKILL.md, breadcrumbs, and help output now point at.

Verification

  • Rebased onto current main after #414 and #467.
  • GOWORK=off make build passed.
  • GOWORK=off go test ./internal/commands ./internal/cli ./internal/presenter ./internal/output passed.
  • GOWORK=off bin/ci passed.
  • GitHub CI is green.
  • Spot-checked that removed shortcuts now error instead of performing writes, while canonical commands still show help.

Summary by cubic

Removed 7 top-level shortcut commands that shadowed plural group nouns to eliminate collisions and accidental writes. Breaking removals (including --version flags on those shortcuts) are acknowledged in .surface-breaking, the surface diff check uses locale-stable sorting, and docs/help/TUI/hooks now point to the plural command groups.

  • Bug Fixes

    • Prevents collisions where singular shortcuts performed creates instead of reads (e.g., basecamp card show ... creating a card).
    • .surface-breaking tracks all removals (including --version on deleted shortcuts); scripts/check-cli-surface-diff.sh sorts with LC_ALL=C for consistent results.
  • Migration

    • card → cards create
    • todo → todos create
    • done → todos complete
    • reopen → todos uncomplete
    • message → messages create
    • comment → comments create
    • react → boost create
    • .surface-skill-drift updated for cards create, todos create, and messages create flags; README, help examples, breadcrumbs, TUI hints, and post-commit hook guidance now use plural commands.
    • STYLE.md now forbids adding new top-level verbs that shadow group nouns.