punkshell/goals/G-082-punkargs-error-selection.md

G-082 punk::args single-form parse error selection: specific validation failures preferred over generic overflow

Status: active Scope: src/modules/punk/args-999999.0a1.0.tm (get_dict/parse error selection, validation-failure capture around the choice/type screens), src/tests/modules/punk/args/testsuites/args/ (characterization + regression suite) Goal: when a single-form parse fails because a word was rejected by an optional argument's validation (restricted choices, type) and consequently overflowed the argument list, the reported error names the specific rejection (the choiceviolation with the offending word and choice list, or the type failure) instead of the generic "Received more values than can be assigned" overflow - restoring the pointedness punk::args 0.5.0-era parsing had for optional choice-restricted leaders/values, and removing the need for the -optional 0 authoring workaround adopted by make.tcl's dispatch definitions. Acceptance: a definition with an optional choice-restricted leader or value that receives a non-matching word reports a choiceviolation-class error naming the word and the allowed choices (message and -errorcode), not toomanyarguments - pinned for the make.tcl-style dispatch shape (optional subcommand leader with choices) and a values-position equivalent; a word rejected by a typed optional argument (e.g int) that then overflows reports the type failure similarly; genuinely-surplus cases (all optional args satisfied, extra word remains) still report toomanyarguments; multiform error selection (rank_form_failures) is unchanged or its pins deliberately updated; current 0.12.x behaviour is characterized first and the pins flipped deliberately; full punk::args suite passes with no expectations weakened; on completion the G-030 -optional 0 workaround sites are revisited (make.tcl dispatch definitions, the src/modules/AGENTS.md "punk::args definition authoring ergonomics" bullet) and relaxed or re-documented.

Context

Found 2026-07-14 during G-030 (make.tcl dogfooding punk::args). make.tcl frobnicate under bootsupport punk::args 0.5.0 reported a pointed choiceviolation naming the word and the subcommand choices; under 0.12.0 the identical definition reports PUNKARGS VALIDATION {toomanyarguments 1 index 0} ("Received more values than can be assigned to argument names"). Verified by A/B probes that the discriminator is -optional 1 on the choice-restricted argument - NOT -choicegroups membership, NOT @form/-synopsis presence, NOT leader-vs-value position (both positions affected).

Worked around in G-030 by declaring the dispatch subcommand/subject arguments -optional 0 - safe there because the dispatch only parses when a word is present, so the required-leader-missing case is unreachable. The workaround is recorded in goals/archive/G-030-maketcl-punkargs.md and as an authoring guideline in src/modules/AGENTS.md "punk::args definition authoring ergonomics" - both should be revisited when this ships.

Assessed mechanism (not yet verified in code): the allocator treats an optional argument whose candidate word fails validation as "argument omitted" and moves on; when no later slot can consume the word, the final error is the overflow, and the earlier, far more informative rejection is discarded. The likely shape of a fix is recording candidate rejections during allocation and preferring the most specific/nearest one at error-report time - the single-form analogue of the multiform rank_form_failures selection.

Notes

• Related: G-073 (unavailable-choice tailored rejection messages want the same "surface the specific rejection" seam - whichever lands first should leave the other a clean hook), G-071 achieved 2026-07-12 (the optional-element allocation machinery this selection logic sits beside - goals/archive/G-071-punkargs-optional-allocation.md).
• Archived-goal references in this file: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md); G-074 achieved 2026-07-13 (goals/archive/G-074-punkargs-multiform-ambiguity-lint.md).