## 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
## What
Adds `--only <skill[,skill,...]>` to `scripts/regen-codex-hashes.sh` and
threads it through `scripts/regen-all.sh` (`--skills` arg /
`REGEN_SKILLS` env), so an agent can regenerate codex hashes for **only
the skills it touched**.
## Why
From `.agents/retro/2026-05-31-bead-crank-postmortem.md` §5 (#1-2): the
codex hash regen rewrites every drifted manifest entry, sweeping ~8-9
pre-existing drifts into every skill PR and forcing a manual
`jq`-splice. Scoping the loop kills that toil.
## Changes
- **`regen-codex-hashes.sh`**: `--only` parses a skill set; the
per-skill loop `continue`s when a skill isn't in the set. `--check`
honors the same scope. Default (no flag) = all skills, unchanged.
`SKILLS_ROOT` is now env-overridable (enables hermetic testing).
- **`regen-all.sh`**: `--skills a,b` / `REGEN_SKILLS=a,b` threads
`--only` into the codex-hash step in both regen and `--check` modes;
trailing NOTE instructs passing scope when only some skills changed.
- **`tests/scripts/regen-codex-hashes-only.bats`**: hermetic — `--only
foo` regenerates only foo and leaves a simulated pre-existing-drift
sibling untouched; no-`--only` regenerates all; `--check` scoping;
comma-list; arg-required.
## Verification
- `bats tests/scripts/regen-codex-hashes-only.bats` — 5/5 pass
- `shellcheck -S warning` clean on both scripts
- `git diff origin/main --stat` scope-only (2 scripts + 1 bats)
- The 9 manifest drifts on `main` (deps, post-mortem, provenance,
red-team, release, scenario, ship-loop, skill-builder, trace) are
**pre-existing**; this PR touches zero `skills-codex/` files.
Closes-scenario: ag-fbe9#regen-scoping
Bounded-context: BC2-Validation
Evidence: scripts/regen-codex-hashes.sh
## What
A one-command finalizer for the ~8 derived registries/goldens a
skill/command addition makes stale.
- `scripts/regen-all.sh` — regenerates every derived artifact in
dependency order (skill counts → domain-map → SKU registry.json →
context-map → embedded skills → COMMANDS.md → cli-surface → codex
hashes).
- `scripts/regen-all.sh --check` — runs the matching drift validators
(no writes) as a pre-push gate.
- `make regen-all` / `make regen-check` targets.
## Why
PR #598 (`ag-nk67`) took **9 CI rounds** to merge — zero feature-code
failures; every red was a stale derived artifact discovered one CI round
at a time (each gate stops at first error, jobs are independent). This
composes the existing generators into one local pass so it's caught
before the first push. Codex twins stay manual (cannot be
auto-authored).
## Verification
`shellcheck --severity=error` clean; `make regen-check` → **all 9 gates
green** on current main.
Closes-scenario: ag-jima#regen-all-finalizer
Bounded-context: BC4-Factory
Evidence: scripts/regen-all.sh
Bo