From 71b388e30a3511736df51efeb960268119fa7569 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 4 Aug 2026 16:02:11 +1000 Subject: [PATCH] G-164 proposed: viability probe alternative-allocation re-probe (reservation-stolen flag words) + G-044 note - new goal (user-drafted 2026-08-04): 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 G-152 viability probe, re-parse with the stolen word(s) consumed as the option they name; pure end-of-input exhaustion after that re-seating grants viable-incomplete. Runtime seating unchanged (the trailing-flag-as-value rule is load-bearing, pinned by flagvalues_plain_then_dash) - surfaced by the G-150 batch + independent second-session review: 'i hash -t' classes the test form '(not viable)' although 'hash -t foo' is valid - a false negative, GAP-pinned in cmdhelp.test (owned by this goal; the pin flips at achievement) - overlap survey in the detail file (G-044 consumer; G-152/G-150 archived relations; args/ns family anchors dismissed as unrelated mechanisms) - G-044 Notes: records G-164 as the probe-layer answer to G-152's "completion consumer lookahead" note for the valmin-reservation class - goals_lint clean (82 active, 82 archived) Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai --- GOALS.md | 4 ++++ goals/G-044-repl-command-completion.md | 1 + goals/G-164-viability-alternative-allocation.md | 17 +++++++++++++++++ 3 files changed, 22 insertions(+) create mode 100644 goals/G-164-viability-alternative-allocation.md diff --git a/GOALS.md b/GOALS.md index 1651bcfe..9e5c4264 100644 --- a/GOALS.md +++ b/GOALS.md @@ -404,3 +404,7 @@ Detail: goals/G-162-bakelist-kit-freshness.md Scope: src/modules/punk/repl-999999.0a1.0.tm (exit/eof done paths, reader-window blocking-restore discipline); src/modules/punk/console-999999.0a1.0.tm (drain helper, -blocking 0 window sites); src/lib/app-punkshell/punkshell.tcl (final-exit seam); ARCHITECTURE.md (Process exit and shutdown section); src/tests/shell/testsuites/punkexe/ (unix-pty-gated drain pin) Detail: goals/G-163-unix-exit-output-drain.md +### G-164 [proposed] punk::args viability probe: alternative-allocation re-probe for reservation-stolen flag words +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) +Detail: goals/G-164-viability-alternative-allocation.md + diff --git a/goals/G-044-repl-command-completion.md b/goals/G-044-repl-command-completion.md index 73546edf..a6622d4e 100644 --- a/goals/G-044-repl-command-completion.md +++ b/goals/G-044-repl-command-completion.md @@ -93,6 +93,7 @@ arginfo principle: introspection must not run commands to elicit usage). -parameters handling; the choice semantics by src/tests/modules/punk/args/testsuites/args/choices.test; forms by forms.test. - G-152 (achieved 2026-08-02 - goals/archive/G-152-punkargs-form-viability-verdict.md) shipped this goal's core verdict enabler: per-form suffix-viability verdicts ('incomplete' = the form is still satisfiable by appending words, sound by construction) in the noformmatch errorcode classes/-formerrors and the parse_status formstatus records, with the consumer contract documented in the parse/parse_status argdocs. Its Notes record two things a completion consumer may need to extend: the trailing-flag-before-restricted-choice seating nuance (verdict is seating-based; flag-pending-value awareness needs consumer lookahead) and the multi-member-clause conservatism (input ending inside a clause reports invalid). +- G-164 (proposed 2026-08-04) is the probe-layer answer to the G-152 note's "consumer lookahead" for one class: the valmin-reservation false negative (a required-flag word stolen into a required value slot at end-of-input - e.g 'i hash -t', where optionmissing stands and the test form classes not viable although the completing suffix 'hash -t foo' exists). G-164 re-probes with the stolen word consumed as the option it literally names, granting viable-incomplete on pure exhaustion; runtime seating stays unchanged. Current state documented by the 0.51.0 CHANGELOG known-issue text and the GAP pin cmdhelp_GAP_multiform_flagled_testform_false_notviable (flips under G-164). - Archived-goal references in this file: G-001 achieved 2026-07-11 (goals/archive/G-001-pluggable-console-backends.md); G-040 achieved 2026-07-08 (goals/archive/G-040-punkargs-choicealiases.md); G-041 achieved 2026-07-13 (goals/archive/G-041-punkargs-form-matching.md). ## Repl behaviour preserve-list + testability findings (2026-07-11, user-directed - pre-refactor ordering) diff --git a/goals/G-164-viability-alternative-allocation.md b/goals/G-164-viability-alternative-allocation.md new file mode 100644 index 00000000..2f15232e --- /dev/null +++ b/goals/G-164-viability-alternative-allocation.md @@ -0,0 +1,17 @@ +# G-164 punk::args viability probe: alternative-allocation re-probe for reservation-stolen flag words + +Status: proposed +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.