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

Author: Copilot

pkg/cli/add_wizard_command.go

@@ -38,8 +38,9 @@ Examples:
 
 Workflow specifications:
   - Two parts: "owner/repo[@version]" (loads repository-root aw.yml package)
-  - Three+ parts without .md: "owner/repo/path[@version]" (tries path/aw.yml; if path is a single segment and no manifest is found, falls back to workflows/path.md)
-  - Four+ parts ending in .md: "owner/repo/path/to/workflow.md[@version]" (loads that explicit markdown workflow path)
+  - Three+ parts without .md: "owner/repo/folder[@version]" (loads nested aw.yml package when present)
+  - Three parts: "owner/repo/workflow-name[@version]" (implicitly looks in workflows/ directory)
+  - Four+ parts: "owner/repo/workflows/workflow-name.md[@version]" (requires explicit .md extension)
   - GitHub URL: "https://github.com/owner/repo/blob/branch/path/to/workflow.md"
   - Local file: "./path/to/workflow.md"
   - Version can be tag, branch, or SHA (for remote workflows)

pkg/cli/add_wizard_command_test.go

@@ -14,3 +14,10 @@ func TestAddWizardCommandMentionsCrush(t *testing.T) {
 	require.NotNil(t, cmd, "Add wizard command should be created")
 	assert.Contains(t, cmd.Long, "Copilot, Claude, Codex, Gemini, or Crush", "Add wizard help should mention all interactive engine options")
 }
+
+func TestAddWizardCommand_UsesStandardThreePartWorkflowSpecWording(t *testing.T) {
+	cmd := NewAddWizardCommand(func(string) error { return nil })
+	require.NotNil(t, cmd)
+
+	assert.Contains(t, cmd.Long, `Three parts: "owner/repo/workflow-name[@version]" (implicitly looks in workflows/ directory)`)
+}

pkg/cli/deploy_command.go

@@ -99,7 +99,7 @@ Examples:
 	cmd.Flags().Bool("no-stop-after", false, "Remove any stop-after field from the workflow")
 	cmd.Flags().String("stop-after", "", "Override stop-after value in the workflow (e.g., '+48h', '2025-12-31 23:59:59')")
 	cmd.Flags().Bool("disable-security-scanner", false, "Disable security scanning of workflow markdown content")
-	cmd.Flags().String("cool-down", defaultDeployCooldown, "Cool-down period before applying a new release during update (e.g. 7d, 24h, 0)")
+	cmd.Flags().String("cool-down", defaultDeployCooldown, coolDownFlagUsage)
 
 	RegisterEngineFlagCompletion(cmd)
 	RegisterDirFlagCompletion(cmd, "dir")

pkg/cli/deploy_command_test.go

@@ -53,6 +53,15 @@ func TestNewDeployCommand_RegistersCoreFlags(t *testing.T) {
 	}
 }
 
+func TestNewDeployCommand_CoolDownFlagUsageMatchesUpdate(t *testing.T) {
+	cmd := NewDeployCommand(func(string) error { return nil })
+	require.NotNil(t, cmd)
+
+	coolDownFlag := cmd.Flags().Lookup("cool-down")
+	require.NotNil(t, coolDownFlag)
+	assert.Equal(t, coolDownFlagUsage, coolDownFlag.Usage)
+}
+
 func TestNewDeployCommand_RequiresRepoFlag(t *testing.T) {
 	cmd := NewDeployCommand(func(string) error { return nil })
 	require.NotNil(t, cmd)

pkg/cli/forecast_command.go

@@ -100,14 +100,17 @@ Examples:
 		},
 	}
 
-	cmd.Flags().Int("days", 30, "Historical window in days to sample run history; must be 7 or 30")
+	cmd.Flags().Int("days", 30, "Historical window in days to sample run history (allowed values: 7, 30)")
 	cmd.Flags().String("period", "month", "Aggregation period for projections: week or month")
 	cmd.Flags().Int("sample", 100, "Maximum number of completed runs to sample per workflow")
 	cmd.Flags().Bool("eval", false, "Evaluate forecast quality against past data (backtesting mode)")
 	addRepoFlag(cmd)
 	addJSONFlag(cmd)
 
 	cmd.ValidArgsFunction = CompleteWorkflowNames
+	_ = cmd.RegisterFlagCompletionFunc("days", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+		return []string{"7", "30"}, cobra.ShellCompDirectiveNoFileComp
+	})
 
 	return cmd
 }

pkg/cli/forecast_test.go

@@ -79,6 +79,15 @@ func TestRunForecast_InvalidDays(t *testing.T) {
 	require.Error(t, err, "should error for days=90 (max is 30)")
 }
 
+func TestNewForecastCommand_DaysFlagDocumentsAllowedValues(t *testing.T) {
+	cmd := NewForecastCommand()
+	require.NotNil(t, cmd)
+
+	daysFlag := cmd.Flags().Lookup("days")
+	require.NotNil(t, daysFlag, "forecast command should register --days")
+	assert.Equal(t, "Historical window in days to sample run history (allowed values: 7, 30)", daysFlag.Usage)
+}
+
 // ── Duration enrichment ───────────────────────────────────────────────────────
 
 // TestDurationEnrichment verifies that the forecast loop computes Duration from

pkg/cli/logs_command.go

@@ -100,10 +100,10 @@ Examples:
   ` + string(constants.CLIExtensionPrefix) + ` logs weekly-research --repo owner/repo  # Download logs from specific repository
 
   # Cache maintenance
-  ` + string(constants.CLIExtensionPrefix) + ` logs --after -1w                # Evict local cache older than 1 week before downloading runs
-  ` + string(constants.CLIExtensionPrefix) + ` logs --after -30d               # Evict local cache older than 30 days before downloading runs
-  ` + string(constants.CLIExtensionPrefix) + ` logs --after -1mo               # Evict local cache older than 1 month before downloading runs
-  ` + string(constants.CLIExtensionPrefix) + ` logs --after 2024-01-01         # Evict local cache older than 2024-01-01 before downloading runs`,
+  ` + string(constants.CLIExtensionPrefix) + ` logs --cache-before -1w          # Evict local cache older than 1 week before downloading runs
+  ` + string(constants.CLIExtensionPrefix) + ` logs --cache-before -30d         # Evict local cache older than 30 days before downloading runs
+  ` + string(constants.CLIExtensionPrefix) + ` logs --cache-before -1mo         # Evict local cache older than 1 month before downloading runs
+  ` + string(constants.CLIExtensionPrefix) + ` logs --cache-before 2024-01-01   # Evict local cache older than 2024-01-01 before downloading runs`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			logsCommandLog.Printf("Starting logs command: args=%d", len(args))
 
@@ -221,7 +221,12 @@ Examples:
 			train, _ := cmd.Flags().GetBool("train")
 			format, _ := cmd.Flags().GetString("format")
 			artifacts, _ := cmd.Flags().GetStringSlice("artifacts")
-			after, _ := cmd.Flags().GetString("after")
+			cacheBefore, _ := cmd.Flags().GetString("cache-before")
+			if !cmd.Flags().Changed("cache-before") {
+				if cmd.Flags().Changed("after") {
+					cacheBefore, _ = cmd.Flags().GetString("after")
+				}
+			}
 
 			// Resolve relative dates to absolute dates for GitHub CLI
 			now := time.Now()
@@ -254,7 +259,7 @@ Examples:
 				}
 			}
 
-			logsCommandLog.Printf("Executing logs download: workflow=%s, count=%d, engine=%s, train=%v, after=%s", workflowName, count, engine, train, after)
+			logsCommandLog.Printf("Executing logs download: workflow=%s, count=%d, engine=%s, train=%v, cache_before=%s", workflowName, count, engine, train, cacheBefore)
 
 			return DownloadWorkflowLogs(cmd.Context(), LogsDownloadOptions{
 				WorkflowName:      workflowName,
@@ -281,7 +286,7 @@ Examples:
 				Train:             train,
 				Format:            format,
 				ArtifactSets:      artifacts,
-				After:             after,
+				After:             cacheBefore,
 			})
 		},
 	}
@@ -310,7 +315,10 @@ Examples:
 	logsCmd.Flags().String("format", "", "Output format for cross-run audit report: pretty, markdown (generates security audit report instead of default metrics table)")
 	logsCmd.Flags().Int("last", 0, "Alias for --count: number of recent runs to download")
 	logsCmd.Flags().StringSlice("artifacts", nil, "Artifact sets to download (default: all). Valid sets: "+strings.Join(ValidArtifactSetNames(), ", "))
-	logsCmd.Flags().String("after", "", "(Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading. Accepts deltas like -1d, -1w, -1mo (or explicit day counts like -30d), or an absolute date YYYY-MM-DD. Unlike --start-date, this only clears local cache and does not filter which runs are fetched.")
+	logsCmd.Flags().String("cache-before", "", "(Cache eviction) Evict locally cached run folders for runs before this date, prior to downloading. Accepts deltas like -1d, -1w, -1mo (or explicit day counts like -30d), or an absolute date YYYY-MM-DD. Unlike --start-date, this only clears local cache and does not filter which runs are fetched.")
+	logsCmd.Flags().String("after", "", "Alias for --cache-before")
+	_ = logsCmd.Flags().MarkHidden("after")
+	_ = logsCmd.Flags().MarkDeprecated("after", "use --cache-before")
 	logsCmd.Flags().Bool("stdin", false, "Read workflow run IDs or URLs from stdin (one per line) instead of discovering runs via the GitHub API")
 	logsCmd.MarkFlagsMutuallyExclusive("firewall", "no-firewall")
 

pkg/cli/logs_command_test.go

@@ -17,7 +17,7 @@ func TestNewLogsCommand(t *testing.T) {
 	assert.Equal(t, "logs [workflow]", cmd.Use, "Command use should be 'logs [workflow]'")
 	assert.Equal(t, "Download and analyze agentic workflow logs with aggregated metrics", cmd.Short, "Command short description should match")
 	assert.Contains(t, cmd.Long, "Download and analyze agentic workflow logs", "Command long description should contain expected text")
-	assert.Contains(t, cmd.Long, "Evict local cache older than 1 week before downloading runs", "Cache maintenance examples should describe eviction plus download behavior")
+	assert.Contains(t, cmd.Long, "logs --cache-before -1w", "Cache maintenance examples should use the cache-before flag name")
 
 	// Verify flags are registered
 	flags := cmd.Flags()
@@ -76,11 +76,16 @@ func TestNewLogsCommand(t *testing.T) {
 	repoFlag := flags.Lookup("repo")
 	assert.NotNil(t, repoFlag, "Should have 'repo' flag")
 
-	// Check after flag (cache maintenance)
-	afterFlag := flags.Lookup("after")
-	assert.NotNil(t, afterFlag, "Should have 'after' flag")
-	assert.Contains(t, afterFlag.Usage, "-1d", "after flag should document day deltas")
-	assert.Contains(t, afterFlag.Usage, "-30d", "after flag should document explicit day-count deltas")
+	// Check cache-before flag (cache maintenance)
+	cacheBeforeFlag := flags.Lookup("cache-before")
+	assert.NotNil(t, cacheBeforeFlag, "Should have 'cache-before' flag")
+	assert.Contains(t, cacheBeforeFlag.Usage, "-1d", "cache-before flag should document day deltas")
+	assert.Contains(t, cacheBeforeFlag.Usage, "-30d", "cache-before flag should document explicit day-count deltas")
+
+	// Backward-compatible alias should remain registered but hidden from help output
+	afterAliasFlag := flags.Lookup("after")
+	assert.NotNil(t, afterAliasFlag, "Should retain hidden 'after' alias")
+	assert.True(t, afterAliasFlag.Hidden, "'after' alias should be hidden from help output")
 }
 
 func TestLogsCommandFlagDefaults(t *testing.T) {

pkg/cli/outcomes_command.go

@@ -59,7 +59,6 @@ Examples:
 		},
 	}
 
-	cmd.Flags().BoolP("verbose", "v", false, "Show detailed output")
 	addJSONFlag(cmd)
 	addRepoFlag(cmd)
 	addOutputFlag(cmd, "")

pkg/cli/outcomes_command_test.go

@@ -0,0 +1,26 @@
+//go:build !integration
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewOutcomesCommand_DoesNotShadowGlobalVerboseFlag(t *testing.T) {
+	cmd := NewOutcomesCommand()
+	require.NotNil(t, cmd)
+
+	assert.Nil(t, cmd.Flags().Lookup("verbose"), "outcomes should not define a local --verbose flag")
+
+	root := &cobra.Command{Use: "gh aw"}
+	root.PersistentFlags().BoolP("verbose", "v", false, "Enable verbose output showing detailed information")
+	root.AddCommand(cmd)
+
+	inherited := cmd.InheritedFlags().Lookup("verbose")
+	require.NotNil(t, inherited, "outcomes should inherit global --verbose flag")
+	assert.Equal(t, "Enable verbose output showing detailed information", inherited.Usage)
+}