feat(parse): add subcommand requirement policy

[jdx]

Summary

• add subcommand_negates_reqs across KDL, derive, argv, clap conversion, and generated Go
• skip parent positive requirements when a child subcommand is selected while preserving conflicts and child requirements
• document the policy and remove the corresponding clap fidelity warning

Verification

• cargo test --all --all-features
• cargo clippy --all --all-features -- -D warnings
• go test ./... (from go/)

AI-generated pull request.

---

Note

Medium Risk
Touches post-parse validation across usage-lib, derive codegen, and generated Go parsers; incorrect gating could hide real missing-arg errors or leave conflicts broken, though tests cover the main cases.

Overview
Adds subcommand_negates_reqs (clap’s subcommand_negates_reqs) end-to-end: KDL/spec, usage_argv::Command, derive #[command(subcommand_negates_reqs)], clap bridge import, conformance tables, and docs/migration notes. PLAN marks this parsing policy as done.

Runtime behavior: when a child subcommand is selected, positive requirements on ancestor commands are skipped—required args/flags, groups, requires / required_if, and similar—while conflicts and the child’s own requirements still run. usage-lib gates checks with requirements_apply over the command chain; the derive skips requirement checks when partial.__usage_selected is set; generated Go builds a per-entry requirements map and uses CheckRelationshipsWithValuesAndRequirements, clearing Required on suppressed entries.

Fidelity: SubcommandNegatesRequirements is removed from the clap loss report because the bridge now preserves the setting. Derive validation allows required on Option fields when this policy is enabled on the parent.

^{Reviewed by Cursor Bugbot for commit 3d9fe17. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 5e61468e-3c5c-4764-9d63-c7a9db7894ed

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3f833ab. Configure here.}

[github-actions]

Instruction counts

Nothing was compared, and so nothing was gated. No series appears on both sides: either the base has no measurements recorded, or the two were measured on different runner classes, which are deliberately not comparable — counts shift between machine types by more than a real regression does.

New, nothing to compare against: markdown on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1, startup on bamboo-v2-ubuntu24.04-x64-30vcpu-24gb-rust1.97.1

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	instructions, cold parse	vs usage
usage	4238	—
argh	6292	1.5x
clap	5893652	1390x
bpaf	21917954	5171x

                                              min       p01       p10    median
usage-rs: argv -> struct                      188       196       198       200  ns
argh: argv -> struct                          265       270       274       281  ns
clap: build tree + parse -> struct         474457    475689    478446    491020  ns
bpaf: build parser + parse -> struct      1577578   1577578   1584811   1600888  ns

usage: argv -> struct                             196 ns      0.20 µs
clap: build tree + parse -> struct             492903 ns    492.90 µs
clap: parse -> struct, tree reused              23457 ns     23.46 µs
clap: build tree only                          304025 ns    304.03 µs

_{3d9fe17bd356 vs ee6d334ef46c · measured on the runner, not pushed to the history.}