Updated in d11d8c0: the compile Long help now states that only --gh-aw-ref is mutually exclusive and that --action-tag can be combined with --action-mode action.

Updated in d11d8c0: the --action-tag Long-help example now uses <full-sha> instead of a short SHA example.

Updated in d11d8c0: CompileConfig.ActionMode comment now says “How action scripts are referenced” to match CLI semantics.

Updated in d11d8c0: CompileConfig.ActionTag example now uses <full-sha> instead of a short SHA example.

script mode is silently accepted by IsValid() but now absent from all help and error guidance — a user passing --action-mode script gets no validation error but nothing tells them the mode exists or is supported.

func (m ActionMode) IsValid() bool {
    return m == ActionModeDev || m == ActionModeRelease || m == ActionModeScript || m == ActionModeAction
}

Addressed in d11d8c0: added an explicit comment in validateActionModeConfig documenting that script is intentionally internal and excluded from user-facing error guidance.

Godoc preamble "when both are provided" makes bullet 2 misleading — a reader may infer that --action-mode dev --action-tag v1 uses dev mode; the code silently uses release instead.

// Priority order:
//   - actionTag != ""                 → pin to that SHA/tag; use ActionModeRelease unless actionMode is explicitly "action"
//   - actionTag == "" && actionMode != "" → honour the explicit mode
//   - neither set                     → auto-detect from the binary build type via DetectActionMode

Updated in d11d8c0: the setupActionMode godoc preamble now removes the “when both are provided” phrasing and explicitly scopes bullet 2 to actionTag == "".

[/tdd] No regression test for the mutual exclusivity enforcement — the core behavior fix has zero test coverage.

func TestCompileGhAwRefMutuallyExclusive(t *testing.T) {
    cases := []struct {
        name string
        args []string
    }{
        {"gh-aw-ref+action-tag", []string{"compile", "--gh-aw-ref", "main", "--action-tag", "v1.2.3"}},
        {"gh-aw-ref+action-mode", []string{"compile", "--gh-aw-ref", "main", "--action-mode", "dev"}},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            rootCmd.SetArgs(tc.args)
            err := rootCmd.Execute()
            if err == nil {
                t.Fatalf("expected mutual-exclusivity error, got nil")
            }
        })
    }
}

Addressed in d11d8c0: added TestCompileGhAwRefMutuallyExclusiveFlags in cmd/gh-aw/main_help_text_test.go to cover both --gh-aw-ref conflict cases.

[/grill-with-docs] "Only one should be used at a time" contradicts the documented ability to combine --action-tag with --action-mode action. Users who read only this header will think the flags are mutually exclusive, then be confused when the flag help says otherwise.

Three flags govern this and only one should be used at a time:

Three flags govern this. --gh-aw-ref is mutually exclusive with the other two;
--action-tag and --action-mode may be combined (e.g. --action-mode action --action-tag v1.2.3):

Updated in d11d8c0: replaced the contradictory “only one should be used at a time” header with wording that matches the actual exclusivity rules.

[/diagnose] The priority-order comment implies sequential evaluation, but the early return on line 223 means the actionMode != "" branch is never reached when actionTag is set — so --action-mode is effectively ignored (except for the action special-case handled inside the tag block). A reader following the godoc might incorrectly conclude that --action-mode dev --action-tag v1.2.3 would honor dev mode.

// setupActionMode configures how gh-aw action scripts are referenced in compiled workflows.
// Resolution order (first match wins; function returns early after the actionTag branch):
//   - actionTag != ""  → pin to that SHA/tag; use ActionModeRelease unless actionMode is
//                        explicitly "action". Returns without evaluating actionMode further.
//   - actionMode != "" → honour the explicit mode (only reached when actionTag is empty)
//   - neither set      → auto-detect from the binary build type via DetectActionMode

Updated in d11d8c0: clarified setupActionMode priority wording so the actionTag branch and actionTag == "" condition for explicit actionMode are clear.

[/diagnose] ActionModeScript.IsValid() still returns true (see action_mode.go:36), so --action-mode script silently passes validation even though the error message no longer lists it as valid. Decide whether script should be accepted at the CLI layer:

// Note: ActionModeScript is intentionally excluded — it is an internal mode
// not meant to be set directly by end users via the CLI.
return fmt.Errorf("invalid action mode '%s'. Must be 'dev', 'release', or 'action'", actionMode)

if mode == workflow.ActionModeScript || !mode.IsValid() {
    return fmt.Errorf("invalid action mode '%s'. Must be 'dev', 'release', or 'action'", actionMode)
}

Addressed in d11d8c0: documented in validateActionModeConfig that ActionModeScript is intentionally internal and omitted from user-facing CLI mode guidance.

[/zoom-out] "full 40-character commit SHA" is overly precise — SHA-1 is 40 hex chars, but the codebase also handles abbreviated SHAs in other contexts and does not validate length here. The prior help text said "full SHA" without the character count, which is more future-proof.

Updated in d11d8c0: --action-tag flag help now says “full commit SHA” (without hard-coding 40 characters).