## What
A ONE-SHOT regenerator (`scripts/regen-command-surfaces.sh`) for the
`ao`-command-landing derived surfaces. When an `ao` command is
added/removed/renamed, these surfaces must update in lockstep — the
multi-surface tax that bit #720 (ag-sz3h, ~4 extra CI rounds):
- the two cobra `expectedCmds` literals in
`cli/cmd/ao/cobra_commands_test.go`
- the `cli-command-surface` heading counts:
`evals/agentops-core/fixtures/cli-command-surface-smoke.sh` +
`evals/agentops-core/cli-command-surface-matrix.json`
## How
- **Single source of truth for the command set**: the LIVE cobra tree,
dumped by the new `TestDumpRegisteredTopLevelCommands` (set
`AO_DUMP_REGISTERED_CMDS=1`). It walks `rootCmd.Commands()` (sorted,
`help` excluded) — exactly the membership the two `expectedCmds`
literals must match. A *test*, not a subcommand, so emitting the list
does not itself add a registered command (which would be circular).
- **Single source of truth for the counts**: `cli/docs/COMMANDS.md`
(itself generated from the cobra tree). `top = ### \`ao `, `sub = ####
\`ao `, `all = #{3,4} \`ao `.
- Rewrites all three derived surfaces deterministically. The
`expectedCmds` literals are reformatted one-element-per-line
(gofmt-stable) so output is canonical forever — **membership is
identical to before (pure reformat)**.
- **Idempotent**: a no-change tree is a no-op; `--check` fails on drift
without writing.
- Wired into `regen-all.sh` (both regen + `--check`) right after the
COMMANDS.md step.
## Deletion ⊃ Addition (completeness note)
Removing/renaming a command is a SUPERSET of adding one. This
regenerator covers the ADD surfaces. A delete/rename ALSO disturbs
surfaces it does NOT auto-regenerate — these need manual/quorum
attention:
- (a) codex-contract gates that hardcode command literals
(`validate-codex-rpi-contract.sh`)
- (b) skills-codex twins/overrides (`export-claude-skills-to-codex` +
`regen-codex-hashes`)
- (c) VERBATIM-PRESERVE template SHAs (`cron-loop-mode.md` frontmatter)
A "deletion ⊃ addition" note is present in the regenerator header
comment AND the `regen-all.sh` operator reminder.
## Verification
- `scripts/regen-command-surfaces.sh` → no-op on clean tree; `--check`
green.
- `go build ./cmd/ao`, `go vet ./cmd/ao`, `go test ./cmd/ao` (full
package) all pass; `gofmt -l` clean.
- `cli-command-surface-matrix` canary: pass. Smoke fixture: pass.
- Pre-push gate's only reds are pre-existing, unrelated canaries
(`context-packet-ab-wave0`, `agentops-core.pre-push-gate-governance`
bats) — not touched by this diff.
Closes-scenario: ag-jy12#command-regen
Bounded-context: BC4-Factory
Evidence: scripts/regen-command-surfaces.sh
Bo