---
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
  modified: 2026-08-28T06:13:38.947Z
---

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 _for this gate_** — it never reaches `spt --help` (the gate only scans clap help / reference.md). ⚠ SCOPE, corrected 2026-08-27: that is a statement about the CLAP surface ONLY, not a general permission. A `///` on a `JsonSchema`-derived manifest type IS published verbatim in `manifest.schema.json` (docs-site + release asset) — see [[manifest-doc-comment-is-a-published-schema-description]], where a wrong one shipped understating a gate's scope. 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]].