Define shared numeric environment/default semantics for count flags

[zeitlinger]

Use case

We are experimenting with the Go generator for OATs, a small CLI with -v/-vv/-vvv and a documented OATS_VERBOSE=3 environment setting. I'd prefer contributing shared behavior upstream rather than teaching an application adapter to reinterpret counts.

For this spec:

flag "-v --verbose" count=#true env="OATS_VERBOSE"

At v6.9.1, generated Go Parse(nil) returns verbosity 0 with OATS_VERBOSE=3. The generator explicitly skips count fallbacks. The Rust reference's environment fallback for a valueless flag instead uses boolean truthiness. That makes this a semantics proposal, not simply a Go bug fix.

Proposed contract

• Resolve a count from argv → env → conditional default → default.
• Count argv occurrences normally: -vvv is 3.
• A CLI occurrence replaces, rather than adds to, an environment/default value: OATS_VERBOSE=3 cli -v is 1.
• Environment/default count values are non-negative decimal integers. Zero is valid; empty, negative, malformed, and overflowing values are errors rather than silently becoming zero.
• Use the same conversion and error behavior across the reference parser, Rust bindings, and generated Go bindings. Agree on a portable range (or explicitly document target-type limits) before implementing overflow checks.
• This does not propose Cobra-style --verbose=3 syntax: unsupported attached values should not silently become one occurrence.

Would this fit the intended count semantics? If so, I'm happy to contribute shared conformance vectors first, then the corresponding implementation and generated-parser regression tests. If counts are intentionally argv-only, a lint diagnostic for incompatible env/default declarations would be preferable to silently accepting them.

I understand usage-go is a development preview; this is feedback from an intentional experiment, not a request for an adoption/stability guarantee.

AI-assisted proposal written using OpenAI Codex.