---
name: clap-doc-comment-leaks-req-tag
description: "A [impl->REQ-X] tag inside a clap `///` arg/command doc-comment leaks the internal REQ code into public `spt --help` + reference.md — put it on an adjacent `//` line"
metadata: 
  node_type: memory
  type: reference
  originSessionId: 712ec375-e0f7-42d6-afab-1b6b84a87330
---

A traceability tag (`[impl->REQ-X]` / `[unit->]` / `[int->]`) placed **inside a clap `///` doc-comment** on a `#[arg]`/subcommand **ships the internal REQ code into public `spt --help` AND the generated docs-site reference.md** — clap renders `///` as the help text. The **docs-token gate (`xtask check`)** rejects it (the W6 "public --help no internal codes" gate, [[v0132-build-drive]] / [[cli-command-docs-drift]]). Bit v0.16.0 W5: a `[impl->REQ-DIGEST-CURSOR]` tag sat in the `///` for `endpoint digest --last/--after`; caught at the RELEASE gate (deployah, fix 9e34161), not the wave's local gate.

**How to apply:** on clap args/commands, put the tag on an **adjacent `//` regular comment above the `#[arg]`** (the pattern the sibling fields use), NOT inside `///`. `//` is invisible to clap help; `///` is public. Evidence is still counted by traceable either way. **Library rustdoc `///` on non-CLI structs/fns is fine** — it never reaches `spt --help` (the gate only scans clap help / reference.md). LESSON: run `xtask check` (docs-token), not just `xtask gen`, before declaring a CLI wave done. Kin [[behavior-change-grep-tests-not-comments]], [[public-docs-version-not-milestone]].