punkshell/goals/archive/G-150-cmdhelp-form-narrowing.md

G-150 punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration

Status: achieved 2026-08-04 Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins) Goal: 'i ?word ...?' (punk::ns::cmdhelp) narrows a flat multi-form command to the form its trailing words select - punk::args form auto-selection, with the whole-command render retained when no form is selectable (no words, option-first lines, ambiguity) - and punk::auto_exec::hash's definition is selection-sound so it exemplifies the mechanism: a flag-led line selects its flag form uniquely instead of today's 'Ambiguous arguments' outcome on a bare parse-withid. Acceptance: 'i ::punk::auto_exec::hash -r' renders only the rehash form's usage and 'i ::punk::auto_exec::hash -d ' only the delete form, driven by the definition (no hash-handler involvement); hash's plain name value carries a flag-excluding constraint (-regexprefail {^-} or equivalent) such that bare punk::args::parse withid selects flag-led forms uniquely, with hash's runtime behaviour otherwise unchanged (a name literally starting with '-' now requires explicit -form selection - the accepted cost); ensembles, single-form commands and no-word invocations render as today (existing cmdhelp behaviour pinned unchanged); the behaviours are pinned in the module testsuites.

Context

From the G-143 finalisation sessions (2026-08-01/02 - archived detail file's Progress notes): cmdhelp tolerates trailing argument words but performs no form narrowing on flat multi-form commands (verified live: 'i punk::auto_exec::hash -t' renders the whole-command help), while make.tcl help gained a dry-run contract that narrows via the same punk::args declarations. Probes verified punk::args honours per-arg -regexprepass/-regexprefail during form matching: with '-regexprefail {^-}' on a plain string value, a flag-led line selects the flag form uniquely; without it, hash's show_or_set form swallows flag-like words as name values and a bare parse-withid reports 'Ambiguous arguments ... match more than one form: show_or_set, rehash'. hash's handler pre-dispatches around this at runtime, so the defect is latent - it blocks exactly the declaration-driven consumers this goal adds.

Notes

• Related: G-044 (proposed) - punk::args-driven interactive completion; form narrowing and completion share the words-to-candidate-forms machinery (see also the noformmatch classes finding recorded in goals/archive/G-143-maketcl-multiform-help.md).
• Related: G-050 (proposed) - punk::ns::synopsis validity marking; sibling punk::ns presentation surface.
• Related: G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md) - the make.tcl help dry-run contract this mirrors at the repl.
• G-152 (achieved 2026-08-02 - goals/archive/G-152-punkargs-form-viability-verdict.md) shipped the suffix-viability verdict this goal's failed/incomplete-line narrowing consumes: formstatus statuses and noformmatch errorcode classes are now sound per-form verdicts, and rendered noformmatch form lines carry '(viable - needs more arguments)' / '(not viable)' markers. Note bootsupport punk::args was still 0.13.0 at G-152 archive time - refresh bootsupport when this goal wants the verdict at the make.tcl surface.
• Overlap survey 2026-08-02: goals_xref paths src/modules/punk/ns-999999.0a1.0.tm src/modules/punk/auto_exec-999999.0a1.0.tm - ns family G-044 G-050 G-052 G-075 G-085 (G-052 autodef docs and G-085 cmdtrace are unrelated mechanisms; G-075 package-id docs tangential); no auto_exec-scoped goals surfaced.
• Activation freshness re-run 2026-08-04 (goals_xref score G-150): no new related goals since drafting - the strongest unlinked pairs (G-055/G-141/G-013/G-109/G-110 term noise on args/word/definition; G-052/G-050/G-044/G-075/G-085 one-directionals already surveyed above) are unrelated mechanisms. No new Related lines required.

Progress

• 2026-08-04 IMPLEMENTED (auto_exec 0.1.1, ns 0.9.2, punkshell 0.51.0): the goal reduced to its declaration half - cmdhelp's G-041 advisory-parse candidacy already narrowed on a unique form selection (verified live pre-change: 'i hash foo' presented show_or_set); the missing piece was hash's selection-soundness. hash's show_or_set name value gained -regexprefail {^-} (mirroring the handler's long-standing first-word rejection of dash-led names), so bare punk::args::parse/parse_status of {-r}/{-d }/{-t } selects rehash/delete/test uniquely (previously multipleformmatches with show_or_set). cmdhelp code unchanged; its subcommand argdoc now states the narrowing contract explicitly. Test-environment gotcha recorded: tcltest setup/body scripts run at namespace level in ::testspace where 'global' is a no-op - the runtime-unchanged pin qualifies ::auto_execs explicitly.
• 2026-08-04 VERIFIED (native tclsh 8.7a6 via runtests.tcl): acceptance pinned in src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (8 new tests: cmdhelp_multiform_flagled_narrowing_rehash / _delete, auto_exec_hash_bare_parse_selects_flag_forms, auto_exec_hash_dashled_name_no_longer_plain, cmdhelp_multiform_nowords_whole_render_retained, cmdhelp_multiform_unknown_flag_noformmatch_whole_render, cmdhelp_multiform_ambiguity_whole_render, auto_exec_hash_runtime_behaviour_unchanged) - cmdhelp.test 40/40; ns subtree green apart from the 2 pre-existing nsprimitives environment failures on this box (verified pristine-failing identically); full source-tree -jobs 16 run at parity with the recorded pre-existing environment failures (21 - 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; commandstack/modpod/offsetstyle separately verified failing identically on the pristine tree in multiproc mode). 'i ::punk::auto_exec::hash -r' / '-d foo' additionally verified live in the interactive table surface (whole header + all-form synopsis with only the selected form's argument table, no ambiguity message) beyond the pinned string/text/dict surfaces. make.tcl modules mint clean (auto_exec-0.1.1.tm, ns-0.9.2.tm); bootsupport/vfscommon promotion left to the next promotion cycle (per the 0.50.1 precedent).

Follow-ons

Follow-on: hash handler's multi-name -t missing-name branch prints "$hash: nm: not found" - undefined variable $hash and literal 'nm:' (auto_exec-*.tm) - pre-existing defect surfaced by this goal's runtime pins, deliberately out of scope => landed 2026-08-04 (user fix in src/modules/punk/auto_exec-999999.0a1.0.tm, folded into auto_exec 0.1.1; regression pin auto_exec_hash_test_multi_missing_name_message in cmdhelp.test) Follow-on: sweep other flat multi-form punk::args definitions for selection-soundness (an unconstrained plain value swallows flag-like words, making every flag-led line ambiguous) - hash was this goal's exemplar; other definitions opt in per-definition => open