3.9 KiB
G-168 Selection-sound launch definitions: script/tclsh forms match dispatch reality
Status: proposed
Scope: src/modules/punk/args/moduledoc/punkexe-999999.0a1.0.tm ((script)::punkexe::script + ::tclsh form discrimination); src/lib/app-punkscript/punkscript.tcl (behaviour oracle, error-surface decision); src/vfs/_config/punkboot_core.tcl (only if the dispatch-parse decision adopts gating, + synced copies via established channels); src/tests/modules/punk/args/testsuites/args/ (new model-parity suite); src/tests/shell/testsuites/punkexe/launcherhelp.test (as touched)
Goal: The two multi-form launch-subcommand definitions are parse-discriminable with existing punk::args vocabulary - form auto-selection agrees with actual dispatch/app behaviour: the file form excludes exactly '-e' (-regexprefail {^-e$}, message naming ./-e), the oneliner form declares the '-e' word as a real element, and tclsh's scriptfile-vs-stdin split (leading-dash words stay argv; incomplete -encoding falls through, stock-style) is expressed through candidacy fall-through - so parse_status verdicts, noformmatch diagnoses and downstream consumers (help depth, completion) see the truth instead of a display-only model.
Acceptance: against the script definition, parse/parse_status select oneliner for {-e ...}, select file for { ...} where ne -e, and {-e} alone reports noformmatch with oneliner viable-incomplete (the app's "-e requires a script argument" reality); against tclsh, {file args} selects scriptfile, a leading-dash word selects stdin, and an incomplete -encoding tail falls through to stdin (stock parity); formcheck reports no unsanctioned findings; a real-vs-model probe matrix (G-055 method) against actual dispatch/app-punkscript behaviour is recorded in this file; whether DISPATCH adopts parse-gating for script/tclsh (tabled pointed errors replacing app-punkscript's plain ones) is decided and recorded with rationale and, if adopted, a measured script-launch latency delta; the new behaviour is pinned in the args testsuite and launcherhelp.test passes unchanged (or with deliberately updated pins named here).
Context
2026-08-05 discussion (formhint arc): 'punk9-dev -e' / 'script -e' error - word-1
'-e' is RESERVED by behaviour (app-punkscript punkscript.tcl:78-88; a file so
named needs ./-e), but the file form declares scriptfile as any string - the
definition is display-honest, parse-dishonest, and the forms cleanly double-match.
The blocker assumed earlier (G-072 negation) is not needed: -regexprefail is
honoured during form matching (verified in the G-143 make.tcl arc, achieved -
goals/archive/G-143-maketcl-multiform-help.md; the G-150 selection-sound hash
declaration is the dash-led-form-word precedent).
Notes
- Enacts the punkexe portion of the G-150 follow-on "sweep other flat multi-form
definitions for selection-soundness" (goals/archive/G-150-cmdhelp-form-narrowing.md);
that follow-on stays open - the sweep is broader than these two definitions.
- The G-144 follow-on (punkexe moduledoc @form -synopsis override set drops once
auto-synopsis serves - goals/archive/G-144-punkargs-synopsis-name-fallback.md,
disposition flipped to this goal) is decided in this work: keep the
placeholder overrides or adopt @cmd -name auto lines - recorded either way.
- Related: G-089 (proposed) - script's lib:name resolution text is consumed scope.
- Related: G-055 (proposed) - the real-vs-model probe method borrowed here.
- Related: G-072 (proposed) - deliberate non-dependency: negation NOT required.
- Related: G-170 (proposed) - consumer: its dry-run arm requires this goal's
parse-trueness.
- Overlap survey 2026-08-05: goals_xref paths over the Scope - G-089 (named
above) is the only substantive live intersection on punkboot_core.tcl;
moduledoc-sibling matches (G-055 G-068 G-072 G-083 G-084 G-166 G-167) are
parser/spec mechanisms or other moduledocs, no availability interaction.