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

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

Status: proposed 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.