Normalize CLI help semantics for verbose/cool-down/days/spec wording and logs cache-eviction flag

[Copilot]

Bug Fix

The CLI consistency checker flagged five help-surface inconsistencies across 33 commands: verbose flag shadowing, divergent --cool-down wording, incomplete --days constraints, add/add-wizard spec wording drift, and ambiguous logs --after naming.

What was the bug?

Help text and flag semantics diverged across commands for equivalent behavior, with one misleading flag name (--after) that implied run filtering while actually performing cache eviction.

How did you fix it?

• Verbose flag consistency (outcomes)

  • Removed local --verbose/-v definition from outcomes so it inherits root/global verbose behavior and wording.

• Unified --cool-down help text (deploy, update)

  • Introduced a shared usage string constant and wired both commands to it.
  • Eliminates wording drift for the same cooldown behavior.

• forecast --days constraint surfaced in flag definition

  • Updated --days help text to explicitly list allowed values: 7, 30.
  • Added shell completion for --days with 7 and 30.

• Aligned workflow spec wording (add, add-wizard)

  • Updated add-wizard “Workflow specifications” bullets to match add for three-part/four-part path semantics.

• Disambiguated logs cache eviction flag

  • Added --cache-before as the primary flag for cache eviction.
  • Kept backward compatibility via hidden deprecated alias --after.
  • Added explicit precedence: if --cache-before is set, it wins; otherwise explicit --after is used.
  • Updated examples/help text to use --cache-before.

Example

logsCmd.Flags().String("cache-before", "", "(Cache eviction) Evict locally cached run folders for runs before this date...")
logsCmd.Flags().String("after", "", "Alias for --cache-before")
_ = logsCmd.Flags().MarkHidden("after")
_ = logsCmd.Flags().MarkDeprecated("after", "use --cache-before")

Testing

• Added/updated focused command tests for:
  • outcomes global verbose inheritance
  • shared --cool-down usage text
  • forecast --days usage wording
  • add-wizard spec wording parity
  • logs --cache-before + hidden alias behavior

[Copilot]

Pull request overview

This PR normalizes CLI help/flag semantics across several commands, mainly aligning shared wording and replacing the ambiguous logs cache-eviction --after flag with --cache-before.

Changes:

• Centralized --cool-down usage text for update and deploy.
• Updated command help/tests for outcomes, forecast, add-wizard, and logs cache eviction.
• Added logs --cache-before with hidden deprecated --after alias handling.

Show a summary per file

File	Description
pkg/cli/update_cooldown.go	Adds shared cooldown flag usage constant.
pkg/cli/update_command.go	Uses shared cooldown usage text.
pkg/cli/update_command_test.go	Tests update cooldown flag usage.
pkg/cli/outcomes_command.go	Removes local verbose flag.
pkg/cli/outcomes_command_test.go	Tests global verbose inheritance.
pkg/cli/logs_command.go	Adds --cache-before, keeps hidden --after alias, updates examples.
pkg/cli/logs_command_test.go	Updates logs flag/help assertions.
pkg/cli/forecast_command.go	Updates --days help and shell completion.
pkg/cli/forecast_test.go	Tests --days help text.
pkg/cli/deploy_command.go	Uses shared cooldown usage text.
pkg/cli/deploy_command_test.go	Tests deploy cooldown flag usage.
pkg/cli/add_wizard_command.go	Aligns workflow spec wording with add command.
pkg/cli/add_wizard_command_test.go	Tests add-wizard spec wording.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 13/13 changed files
• Comments generated: 2