---
name: cli-command-docs-drift
description: "Adding/changing a CLI command requires `xtask gen` (regen CLI ref) + NO milestone/REQ codes in the clap help — the docs-drift gate is CI-gated"
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 30df62c3-0b22-4b14-88de-fef422a5554f
---

Adding or changing a `spt` CLI command (clap enum variant / args) has TWO CI-gated obligations beyond build+clippy+tests:

1. **Regenerate the CLI reference:** `cargo run -p xtask -- gen` rewrites `docs-site/src/cli/reference.md` from the binary's `--help`. The **docs-drift gate** (`cargo run -p xtask -- check`, CI step "Docs drift gate (CLI ref + llms links)") fails on BOTH runners if the checked-in ref ≠ current `--help`. It fires independently of traceable. Verify with `xtask check: OK` before pushing.
2. **No internal codes in the clap `///` help:** the doc-comment on a clap variant/arg IS the `--help` text, so it lands verbatim in the PUBLIC CLI ref. Keep `M#-W#` / `REQ-*` / "wave" OUT of the user-facing `///` (put them in separate `// [impl->REQ-X]` code-tag comments instead). See [[public-docs-version-not-milestone]].

**Why:** M11-W2 first CI run went RED on the docs-drift gate (both runners) — the new `spt shell drive` / `api drive-poll` were missing from the ref, and my clap help comments leaked `(M11-W2, REQ-SHELL-3)`. Fix = strip the codes + `xtask gen` + commit the regenerated ref (@9d5fb63).

**How to apply:** after any cli.rs / api/mod.rs surface change, run `xtask gen` then `xtask check`, grep the diff of reference.md for `M[0-9]+-W|wave|REQ-` in ADDED lines, and commit the regenerated doc with the code change.