punkshell/goals/archive/G-164-viability-alternative-allocation.md

G-164 punk::args viability probe: alternative-allocation re-probe for reservation-stolen flag words

Status: achieved 2026-08-04 Scope: src/modules/punk/args-999999.0a1.0.tm (G-152 viability probe - private::get_dict_form optional 4th arg); src/tests/modules/punk/args/testsuites/args/formviability.test; src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (GAP flip) Goal: When the valmin reservation seats a word that literally names a declared required option into a required value slot, and the resulting optionmissing stands in the viability probe (a value word consumed), the probe re-parses with the stolen word(s) consumed as the option they name; pure end-of-input exhaustion after that re-seating grants 'incomplete' (viable). Runtime seating is unchanged - the trailing-flag-as-value rule is load-bearing. Acceptance: 'i ::punk::auto_exec::hash -t' classes the test form viable (incomplete) while show_or_set/rehash/delete/help remain not viable, and {-d} classes delete viable; no parse RESULT changes anywhere (runtime seating untouched): full args and ns subtrees green apart from the deliberate GAP flip, with flagvalues_plain_then_dash (trailing-flag-as-value) and the runtime 'missing flags' message path pinned unchanged; the GAP pin cmdhelp_GAP_multiform_flagled_testform_false_notviable flips to the viable assertion.

Context

Surfaced by the G-150 batch (2026-08-04, punkshell 0.51.0): removing the help form's adhoc-option-viable marker left 'i hash -t' with every form "(not viable)" - correct for help/show_or_set/rehash/delete but a false negative for test, since 'hash -t foo' is a valid test line. Mechanism (verified live): the valmin reservation (the option-scan guard reserving remaining words for required values) seats the lone -t as the required name value without comparing it to the declared -t option; the G-152 position guard (missing-required-option suppressed only when no value words consumed) then lets optionmissing stand. Not one of G-152's documented conservatisms (those cover the multi-member clause case; the seating-based philosophy note covers trailing defined flags before unconstrained optional or restricted-choice values - this is the required-value reservation class). Independent review (second session, 2026-08-04) assessed the batch and recommended exactly this probe-layer refinement plus GAP-marking of the false negative (the GAP pin is applied in cmdhelp.test) - with the constraint: do NOT change the runtime reservation, which is load-bearing (an optional solo -x with @values -min 1 parses {-x} as a value today, pinned by flagvalues_plain_then_dash).

Notes

• Related: G-044 (proposed) - punk::args-driven interactive completion; the verdict's primary consumer. Its Notes record this goal's re-probe requirement for its lookahead.
• Related: G-152 (achieved 2026-08-02 - goals/archive/G-152-punkargs-form-viability-verdict.md) - the suffix-viability verdict layer this refines; its 'deliberately seating-based' note already records that a completion consumer wanting flag-pending-value awareness needs its own lookahead - this goal is that lookahead, at the probe layer.
• Related: G-150 (achieved 2026-08-04 - goals/archive/G-150-cmdhelp-form-narrowing.md) - the batch that surfaced the false negative; its cmdhelp.test GAP pin (cmdhelp_GAP_multiform_flagled_testform_false_notviable) flips here.
• Overlap survey 2026-08-04: goals_xref paths src/modules/punk/args-999999.0a1.0.tm src/tests/modules/punk/args/testsuites/args/formviability.test src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test - the args family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088 G-149 G-151) via the ubiquitous args-module anchor and the ns family (G-050 G-052 G-075 G-085) via the shared cmdhelp.test anchor; G-044 named above as the consumer, the rest are unrelated parse/render mechanisms. G-152/G-150 (archived) named above.
• Activation freshness re-run 2026-08-04 (goals_xref score G-164, at user-directed activation same day as drafting): no new related goals - the one-directional args/ns-family pairs are the goals already surveyed above; the unlinked pairs (G-158/G-110/G-055/G-019/G-028 et al) are term noise on runtime/load/plain/required. No new Related lines required.

Progress

• 2026-08-04 IMPLEMENTED (punk::args 0.15.1, punkshell 0.51.1): the alternative-allocation re-probe landed in private::get_dict_form. The valmin reservation's option-scan seating site now records the words it seats without an option check (reservation_seated); at the optionmissing raise in probe mode, when reservation-seated words literally name missing required options (exact match against the option's declared spellings), the probe re-parses via a {1 reseat_words} viabilitycheck argument with those words consumed as the options they name (the reservation break is bypassed for exactly those words); a re-seated parse failing only on pure end-of-input exhaustion (or clean) passes the probe. Options still missing after the re-seating are ordinary exhaustion in the re-probe (no value words precede them), so {-t} on a two-required-flag form is viable too. A stolen word naming a value-TAKING required option stays conservative: re-seated, it seats as a value again at end-of-input (the trailing-flag-as-value rule) and the optionmissing stands. Runtime seating untouched - the re-probe runs only inside the probe. Verdict contract documentation updated in the parse argdoc 'Multiform failure contract' and the parse_status argdoc formstatus section.
• 2026-08-04 VERIFIED (native tclsh 8.7a6 via runtests.tcl): acceptance pinned - formviability.test +7 tests (17/17: re-probe grants viable ranked-first with siblings invalid, delete-form {-d} viable, other-missing-options exhaustion, unnamed stolen word stays invalid, value-taking conservatism, runtime seating unchanged (optionmissing single-form / noformmatch multiform), single-form formstatus); the cmdhelp.test GAP pin flipped to cmdhelp_multiform_flagled_testform_viable (45/45). 'i ::punk::auto_exec::hash -t' verified live rendering "form 'test': (viable - needs more arguments)" with show_or_set/rehash/delete/help "(not viable)"; 'i hash -d' renders delete viable. args + ns subtrees green apart from the 2 pre-existing nsprimitives environment failures on this box; full source-tree -jobs 16 run at parity with the recorded pre-existing environment failures (exec.test 5, argparsingtest 5, commandstack 1, modpod roundtrip 1, lib compat lpop 1, nsprimitives 2, repl consolebackends/nscurrent SIGILL 4, zipreader 2, offsetstyle 1 - none args-related; flagvalues_plain_then_dash and the runtime optionmissing message path pinned unchanged). make.tcl modules mint clean (args-0.15.1.tm, args-0.15.0.tm pruned); bootsupport/vfscommon promotion left to the next promotion cycle (per the 0.50.1 precedent).

Follow-ons

Follow-on: a stolen word naming a value-TAKING required option stays conservative (invalid) - re-seated, it seats as a value again at end-of-input (the trailing-flag-as-value rule) although a completing suffix exists (e.g {-dest x foo}); a further probe layer could re-seat with the option's own value also supplied - candidate refinement if the G-044 completion consumer needs it => open