# feat: gate experimental commands behind build-time visibility flag

`8622db2`→[main](/content/gh/entireio/cli/commits/main/index.html)·

gtrrz-victor·1w ago·12 files·+400 added/-51 removed

Introduce cmd/entire/cli/experimental: a build-time gate (Visible, stamped false by GoReleaser via ldflags) that shows a curated set of maturing commands in developer builds and hides them in shipped releases. When visible, they are filed under a single 'Experimental commands:' cobra group in help; when hidden they carry no GroupID so release help is unchanged and cobra never references an unregistered group.

Gated (visible in dev, hidden in release, always runnable): tokens, import, review, investigate, blame, why, search, experts, runner (root) and checkpoint policy. Infra/plumbing, deprecated shortcuts, and aliases are untouched and stay always-hidden.

- .goreleaser.yaml stamps experimental.Visible=false (nonprod builds only git-remote-entire, so no stamp needed there).
- Add 'mise run build' (plain go build; experimental visible).
- Update existing tests that asserted these commands were Hidden to assert the experimental grouping instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

## Sessions

01KX5KJ6CM021TCW330YVEH7ASView transcript

## Changes

12

- M.goreleaser.yaml+2

- cmd/entire/cli

- Mcheckpoint_group.go+2/-1

- experimental

- Aexperimental.go+50

- Aexperimental_test.go+100

- Aexperimental_wiring_test.go+117

- Mexperts_test.go+7/-3

- Minvestigate_bridge_test.go+10/-4

- Mlabs_test.go+53/-11

- Mroot.go+24/-21

- Mroot_test.go+12/-6

- docs/superpowers/specs

- M2026-07-10-experimental-command-gating-design.md+19/-5

- Mmise.toml+4

```Go
25 unmodified lines
```

### Package experimental

```Go
// Package experimental gates the visibility of experimental CLI commands.
// 
// Experimental commands stay fully runnable in every build; this package only
// controls whether they appear in `entire help`. Developer builds (go build,
go run, mise) show them, grouped under an "Experimental commands:" help
// section. Release builds (GoReleaser) hide them. 
package experimental

import "github.com/spf13/cobra"

// Visible controls whether experimental commands are shown in help. It is
// stamped by GoReleaser via ldflags
// (-X github.com/entireio/cli/cmd/entire/cli/experimental.Visible=false)
// to hide them in shipped binaries. It defaults to "true", so every
// non-release build (go build, go run, mise) shows them. The commands remain
// experimental and fully runnable regardless of this flag — it only toggles
// visibility.
var Visible = "true"

// IsVisible reports whether experimental commands are shown in help.
func IsVisible() bool { return Visible != "false" }

// GroupID is the cobra group experimental commands are filed under.
const GroupID = "experimental"

const groupTitle = "Experimental commands:"

// Register adds child under parent as an experimental command.
// 
// When experimental commands are visible, child is filed under parent's
// "Experimental commands:" help group (registering the group on parent once).
// When hidden, child is marked Hidden and left ungrouped — so release help
// never carries an empty group header, and cobra never references a group ID
// that was not registered.
// 
// Register overrides any Hidden value the child's constructor set, so callers
do not need to touch the constructors (including ones in other packages).
func Register(parent, child *cobra.Command) {
	if IsVisible() {
		if !parent.ContainsGroup(GroupID) {
			parent.AddGroup(&cobra.Group{ID: GroupID, Title: groupTitle})
		}
		child.Hidden = false
		child.GroupID = GroupID
	} else {
		child.Hidden = true
		child.GroupID = ""
	}
	parent.AddCommand(child)
}
```

- `testing`

```Go
// experimentalRootCommands are the top-level commands gated behind the
// experimental visibility flag. Names match cobra's Command.Name() (the first
// token of Use).
var experimentalRootCommands = []string{
	"tokens", "import", "review", "investigate",
	"blame", "why", "search", "experts", "runner",
}

// withVisible sets the experimental visibility flag for the test and restores
// it afterward. Because it mutates a package global, callers must not run in
// parallel.
func withVisible(t *testing.T, v string) {
	t.Helper()
	prev := experimental.Visible
	experimental.Visible = v
	t.Cleanup(func() { experimental.Visible = prev })
}
```

The provided code and explanations rely entirely on the semantic context of the original markdown content, focusing on the introduction and workings of the experimental command gating system within the CLI framework. Relevant coding examples are included to preserve technical particulars.