feat(spec,parse): add repeatable clause groups

[jdx]

Summary

• add separator-delimited repeatable clause declarations
• group each clause instance independently in interpreted parse output
• restart flags, positional state, and automatic trailing-value behavior at clause boundaries
• protect literal separators after explicit double dash
• add clause-aware completion, documentation, fixtures, and validation

Stack

• Depends on feat(complete): complete sigil-prefixed positionals #1319

Test plan

• cargo test -p usage-conformance --test clause --test reference
• cargo test -p usage-cli complete_word_clause
• mise run lint

AI-assisted — Tool: Codex; model: OpenAI/GPT-5; version: unavailable.

---

Note

Medium Risk
Core argv parsing and validation behavior change in usage-lib with new output shape (clauses); completion logic is updated, but adopters must opt into clause specs and bump to 6.6.

Overview
Release 6.6.0 introduces clauses: repeatable, separator-delimited groups of positional args that keep every instance (unlike restart_token, which only retains the last).

Specs gain a clause KDL node (one per command, positional arg children only; mutually exclusive with top-level args, restart_token, and sigil args). Parse output adds ParseOutput::clauses and TokenRole::ClauseSeparator. The parser routes positionals through active_args, splits on the separator even after double_dash="automatic", re-enables flags at boundaries, and skips env/defaults inside clause instances. Per-instance validation covers required args, variadic bounds, and requires / conflicts / required_if* rules; a new MissingClauseArg error is exposed.

Shell completion treats clause separators like restart tokens for restarting positional completion at the first inner arg. Docs add a clauses reference page and link it from cmd; an example spec and conformance tests cover parsing, -- protection, KDL round-trip, and relationships.

^{Reviewed by Cursor Bugbot for commit 685848a. 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: 919a8299-f3a8-49a0-818d-042c3b90a286

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.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁█	339,009,043 → 341,615,158	+0.77%	29.29 → 28.51ms	-2.67%
startup	▁█	908,968 → 910,178	+0.13%	0.89 → 0.90ms	+0.33%

No instruction-count regression above 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	stripped binary, bytes
usage	1328976
bpaf	2493280
clap	3101832

framework	instructions, cold parse	vs usage
usage	8441	—
clap	6315228	748x
bpaf	21909141	2595x

                                              min       p01       p10    median
usage-rs: argv -> struct                      419       421       423       426  ns
clap: build tree + parse -> struct         522533    523430    525190    529118  ns
bpaf: build parser + parse -> struct      1598727   1598727   1607168   1622056  ns

usage: argv -> struct                             458 ns      0.46 µs
clap: build tree + parse -> struct             534798 ns    534.80 µs
clap: parse -> struct, tree reused              23929 ns     23.93 µs
clap: build tree only                          327525 ns    327.53 µs

_{685848aaacbc vs 5c3c3a1d8bb2 · measured on the runner, not pushed to the history.}

[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 715e8a5. Configure here.}