Define a documented convention for pairing short and long option names in specs

[vikvang]

Specs are inconsistent about whether equivalent short/long options are modeled as separate entries or as a paired name array (e.g. ["-d", "--max-depth"]). Contributors adding long forms don't have a documented convention to follow, which shows up in review churn. Requesting a written spec that defines the pairing convention (when to pair vs separate entries, how exclusiveOn lists should reference paired options) and where it should be documented for contributors.

[warp-factories]

Thanks for the report — the factory has picked this up and is running triage. I'll follow up here with a summary and labels shortly.

Responding as Warp for OSS: Open session · View run

[warp-factories]

Thanks for filing this — the gap is real and actionable.

Verdict: valid documentation request (contributor convention), and directly observable in the tree.

What we confirmed

• The schema permits either form: option name deserializes as one-or-many (completion-metadata/src/fig_types.rs:167), so both "name": "-d" and "name": ["-d", "--max-depth"] are valid.
• Hand-written specs genuinely disagree in practice — across command-signatures/json/, ~14.3k option entries use a paired name array while ~38.5k use a single string, and 355 files contain at least one paired entry vs 431 containing at least one string entry. Paired short/long is the norm in GNU-style specs (head.json uses ["-c","--bytes"], ["-q","--quiet","--silent"]; likewise curl.json, grep.json), while others stay short-only or mixed (du.json, ls.json, find.json, parts of df.json).
• exclusiveOn is widely used in the JSON and is deserialized (fig_types.rs:190-191), but it is never read by the runtime today — it is not carried onto the runtime Opt. A naming convention still matters for authors and for review consistency.
• README.md, AGENTS.md, and .agents/skills/add-command-spec/SKILL.md contain no guidance on when to pair names or how exclusiveOn should list aliases.

Suggested direction
Document a short convention for contributors: pair equivalent short/long forms on a single option; keep separate entries only where semantics differ; when using exclusiveOn, list every alias a user might type for the conflicting option; and when adding a long form to an existing short-only option, update peer exclusiveOn lists that named only the short form. Landing the convention does not require rewriting existing specs — migration can be opportunistic. #372 (du / --max-depth) is a concrete case that depends on this.

Reproducibility: high

Routing to @captainsafia to review and apply a gate label (ready-to-spec / ready-to-implement) if this should proceed.

Responding as Warp for OSS: Open session · View run

[warp-factories]

Gate received — thanks. Now drafting the written convention, which will land as a draft PR linked back here for review.

Scope note: the convention will be documented without rewriting the existing corpus (migration stays opportunistic), and it won't imply inventing GNU long forms for BSD/macOS-oriented specs. That exclusiveOn is currently parsed but not enforced at runtime is being recorded as an open question for a maintainer, not changed here.

Responding as Warp for OSS: Open session · View run

[warp-factories]

Spec is up as a draft PR: #375 (specs/GH374/product.md, specs/GH374/tech.md), and a maintainer has approved it (plan-approved).

It settles the three things asked for here: scalar name for a single documented spelling vs. an array for fully equivalent aliases; exclusiveOn listing every literal alias of each conflicting option; and README.md as the canonical contributor-facing home, linked from the command-spec skill so contributors and agents share one source. Migration stays opportunistic, and it does not imply inventing GNU long forms for BSD/macOS-oriented specs.

Implementation now waits on ready-to-implement here — a maintainer-only gate the factory won't apply itself.

Responding as Warp for OSS: Open session · View run

[warp-factories]

ready-to-implement received — both gates are now clear (spec approved in #375). Implementation is underway against the approved spec and will arrive as a separate draft PR linked here.

Scope stays as approved: contributor documentation only (README.md plus a pointer from the command-spec skill). No spec JSON, Rust, or generator changes, and no alias additions — including the du / --max-depth case in #372, which remains out of scope.

Responding as Warp for OSS: Open session · View run

[warp-factories]

Implementation is up as a draft PR: #376, documenting the convention in README.md with a pointer from the command-spec skill. Review requested from @captainsafia.

Both PRs are now open for maintainers: #375 (the approved spec) and #376 (the implementation). Nothing in the corpus was rewritten, and no aliases were added — #372 (du / --max-depth) is still open and unaffected.

Responding as Warp for OSS: Open session · View run