punkshell/goals/G-084-punkargs-parsekey-completeness.md

G-084 punk::args -parsekey completeness: cross-member -multiple collection, leaders/values support, defined default precedence

Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (parse paths, resolve directive handling for @leaders/@values), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (sites carrying '#todo - fix -parsekey for leaders and values'), src/tests/modules/punk/args/testsuites/args/parsekey.test + testsuites/dev/parsekey-knownbugs.test (GAP/known-bug flips) Goal: -parsekey behaves as a complete, position-independent result-keying mechanism: distinct -multiple members sharing a parsekey accumulate under the shared key in received order (no silent value loss), -parsekey on leaders and values renames their result/received keys the same way it does for options (or is rejected at define time everywhere it is unsupported - no silent ignore, no parse-time abort), and the precedence rule for multiple defaulted members of one group is documented behaviour rather than an in-code '? review'. Acceptance: the three punkargsKnownBug tests in testsuites/dev/parsekey-knownbugs.test are enabled and pass (or are amended to the settled design and pass); the corresponding _GAP pins in parsekey.test are flipped or retired; the '#todo - fix -parsekey for leaders and values' moduledoc comment is resolved; the full existing punk::args suite passes untouched.

Context

Probe findings from the 2026-07-14 parsekey coverage review, each pinned by a _GAP test in src/tests/modules/punk/args/testsuites/args/parsekey.test:

• Cross-member -multiple value loss: with -add and -sub both -multiple 1 sharing parsekey -op, parsing -add a -sub b -add c returns -op b - the collected -add occurrences {a c} vanish. Occurrences are collected per member flag and the shared-key resolution then returns only one member's list (parsekey_shared_key_multiple_collection_GAP).
• -parsekey on a value is accepted at define time but ABORTS parsing with an internal error; on a leader it is silently ignored; the @values directive line rejects it as an unrecognised key (parsekey_values_leaders_GAP). The tclcore moduledoc carries #todo - fix -parsekey for leaders and values next to a definition using it, and choices.test notes a leaders/values parsekey mechanism would help multi-element clause choice grouping.
• When more than one member of a shared-parsekey group declares -default, the last-defined member's default wins - the ordered_opts default handling in the source carries a literal ? review (parsekey_shared_key_member_defaults_GAP).

Approach

• Accumulate-in-received-order is the lean for cross-member -multiple collection, pinned (disabled) in dev/parsekey-knownbugs.test as parsekey_shared_key_multiple_accumulation. Open design decision: once G-083's relations vocabulary exists, "error on cross-member combination unless permitted" is a defensible alternative - decide before activating.
• Leaders/values support should reuse the option path's keying rules (result + received dicts, required-list satisfaction) rather than a parallel mechanism; where support is deliberately not implemented, define time must reject the key with a clear message instead of deferring failure to parse.
• The defaulted-members precedence rule (whatever is settled) gets stated in the -parsekey documentation and the ? review comment removed.

Notes

• Desired-behaviour pins (disabled behind punkargsKnownBug): src/tests/modules/punk/args/testsuites/dev/parsekey-knownbugs.test - enable and flip the parsekey.test _GAP pins as fixes land.
• Related: G-083 (argument relations - shared design context for the cross-member collection decision), G-053 (occurrence arity of a single argument).