punkshell/goals/archive/G-170-launcher-help-depth.md

G-170 Launcher help depth: form narrowing, parse-true dry-run, actionable form hints

Status: achieved 2026-08-06 Scope: src/vfs/_config/punkboot_core.tcl (help arm, + synced copies via established channels); punkexe launch definitions wherever homed after G-168/G-169 (formhint un-suppression); src/tests/shell/testsuites/punkexe/launcherhelp.test Goal: Launcher help gains per-form depth without breaking the prepend-help idiom: 'help _{<formname|index>' narrows any multi-form definition to that form's usage (the G-150 cmdhelp/usage -form precedent); for parse-true subcommands (G-168 built-ins; project registrations with parse=1) the help tail MAY dry-run make.tcl-style - accepted lines render the matched form plus the received-args report, rejected lines emit dispatch's own diagnosis - while passthrough subcommands keep ignored tails exactly as today; and the 0.6.1 interim -formhint suppression is replaced with actionable ' help %formname%' templates, resolving the circularity objection (the hint names real navigation). Acceptance: 'help script oneliner' (and an index form) renders only that form's usage; a non-form trailing word on a passthrough subcommand keeps today's ignored behaviour (prepend-help pinned unchanged); for a parse-true subcommand the dry-run's accept/reject agrees with dispatch on the same words (parity pinned); the form-word-vs-scriptfile collision rule (a script literally named 'oneliner') is decided and documented; the multi-form definitions' -formhint suppression flips to real templates and the hint labels render them; every increment has a working degraded/plain twin; all pinned in launcherhelp.test.}

Context

The G-149 make.tcl adoption (2026-08-05 - goals/archive/G-149-punkargs-formhint-labels.md) showed the hint pattern; the launcher suppressed instead (punkexe moduledoc 0.6.1) because subject-only help offered no per-form destination. This goal builds the destination, then points at it.

Notes

• Depends on G-168 (achieved 2026-08-05 - goals/archive/G-168-selection-sound-launch-definitions.md) for the dry-run arm (narrowing arm is standalone) - now satisfied: the script/tclsh forms are parse-discriminable and the dry-run arm inherits one recorded LIMIT (the complete '-encoding ' shape raises a sanctioned multipleformmatches naming both forms - the honest two-form diagnosis for that line; G-168's Progress records the rationale).
• Related: G-169 (achieved 2026-08-05 - goals/archive/G-169-app-owned-launch-docs.md) - the defs' home determines where templates land: now decided - the script definition (and its interim -formhint "" suppression this goal replaces) lives in src/lib/app-punkscript/punkscript.tcl (app-punkscript-docs); tclsh and the other core-owned definitions stay in the punkexe moduledoc. The un-suppression arm edits BOTH homes.
• Related: G-151 (achieved 2026-08-05 - goals/archive/G-151-punkargs-annotated-success-render.md) - the dry-run arm's received-args report is G-151's punk::args-level annotated success render, now landed as punk::args::parse_report (punk::args 0.18.0, with the ansistring TRUNCATE elision primitive in punk::ansi 0.2.0): the launcher's dry-run arm consumes it directly instead of hand-assembling a second interim make.tcl-style one-liner (make.tcl's own interim report retirement is an open G-151 follow-on gated on a bootsupport promotion). Cross-link added 2026-08-05 at G-151 drafting (the drafting overlap survey was path-based and could not surface G-151's args-module scope); sequencing lean honoured - G-151 landed first.
• Related: G-044 (proposed) - completion later consumes the same candidacy data.
• Related: G-167 (proposed) - recorded at activation 2026-08-06 (activation-freshness survey re-run): its @form availability filter and annotated form lines flow through the same usage/-form render path the narrowing arm consumes - if G-167 lands, narrowed launcher help inherits availability annotation automatically; no sequencing constraint (the narrowing arm renders whatever usage renders).
• Archived precedents: G-143 (achieved - goals/archive/G-143-maketcl-multiform-help.md, make.tcl dry-run), G-150 (achieved - goals/archive/G-150-cmdhelp-form-narrowing.md, usage -form narrowing), G-032 (achieved - goals/archive/G-032-launcher-punkargs.md, launcher help mechanism), G-149 (achieved - goals/archive/G-149-punkargs-formhint-labels.md, formhint mechanism + suppression).
• Overlap survey 2026-08-05: shared with the G-168/G-169 survey; no additional live intersections beyond those named.

Progress

Achieved 2026-08-06 in one session (user-directed activation and implementation same day; punkboot core 0.7.0, punkexe moduledoc 0.9.0, app-punkscript/app-punkscript-docs 1.3).

Mechanism landed (punkboot_core.tcl 0.7.0; both layout copies synced byte-identical - project-0.1 + modpod-template):

• launcher_show_help gains a tailwords parameter and returns the suggested exit code (0 for every render, 1 only for a rejected dry-run); the dispatch help arm passes [lrange $subcommand_arglist 1 end] and exits with the return. Subject validation is unchanged (launcherhelpsubject clone, subject word only, prefixes resolve).
• Narrowing arm: a SINGLE tail word on a multi-form definition that exactly matches a form name, or is a decimal ordinal below the form count, renders 'punk::args::usage -form ' - the G-150 narrowing shape (all-form synopsis retained, the selected form's argument table only). Display-only, any definition vintage, any subject with a multi-form id (built-in or project-registered).
• Dry-run arm (launcher_dryrun_capable): any other tail parses through the subject's definition exactly as make.tcl help does (G-143 shape: punk::args::parse -errorstyle [launcher_errstyle] withid). Accepted lines render the matched form's usage (-form from the parse result on multi-form defs) plus the punk::args::parse_report landing report (G-151; guarded - an older punk::args without parse_report renders the usage alone). Rejected lines emit the parse diagnosis on stderr, exit 1.
• Parse-true set: buildinfo and project parse=1 registrations have parity with dispatch BY CONSTRUCTION (dispatch parses the same id); script/tclsh are declared passthrough surfaces whose G-168 selection-sound definitions MODEL dispatch/app reality, so their dry-run additionally requires the fence witness - at least one -regexprefail row in the definition actually served. A pre-G-168 (unfenced) moduledoc snapshot - the real mixed promotion state: current core beside an older baked kit stack - keeps the historic ignored-tail render instead of misdiagnosing lines whose forms double-match (probed live: current core + baked 0.6.1 moduledoc, 'help tclsh somefile somearg' renders exit 0 where an ungated dry-run would raise multipleformmatches exit 1). 'help' itself is deliberately NOT parse-true: its tail handling IS this dispatch ('help help ' keeps the clone render). shell/punk/shellspy: passthrough, tail ignored exactly as before.
• Formhint un-suppression at BOTH homes (the G-169-decided split): (script)::punkexe::script in src/lib/app-punkscript/punkscript.tcl (app-punkscript 1.3) and (script)::punkexe::tclsh in the punkexe moduledoc (0.9.0) replace '@cmd -formhint ""' with the template ' help _{%formname%'. The labels render beside each form's synopsis line and name real navigation - the 0.6.1 circularity objection is resolved. (script)::punkexe::help's @cmd/arg text documents the depth semantics (the 'accepted and ignored (reserved)' arg row cashed in).}

Decisions recorded:

• Collision rule (the acceptance's decision item): in the single-trailing- word position the form word WINS over argument interpretation - matching is EXACT form names plus decimal ordinals only (no prefix resolution: the tighter the match rule, the smaller the shadow over the subject's own first-argument space). A file literally named like a form stays dry-runnable via a path spelling ('./oneliner' parses as the file form's scriptfile - probed live), the same reachability dodge G-168 recorded for a file named '-e' (./-e). Documented in the help definition, the core comments and both formhint comment blocks.
• NO trailing ellipsis on the launcher hint templates, deliberately diverging from make.tcl's ' make.tcl help tool %formname% ...' shape: the display-hint honesty rule marks ACCEPTED CONTINUATIONS OF THE SAME OPERATION, and make.tcl's form words are literal action leaders whose continuation refines the same dry-run - the launcher's form word is pure navigation, and appending words flips the tail into the dry-run interpretation (a different operation). The exact hinted line is the complete narrowing command.
• 'renders only that form's usage' means the G-150 narrowing shape it cites: whole header + all-form synopsis (hint labels included) with only the selected form's argument table.
• The dry-run arm inherits the recorded G-168 LIMIT unchanged: the complete '-encoding ' tclsh line raises the sanctioned multipleformmatches diagnosis naming both forms (stderr exit 1) - the honest two-form answer for that line (stock's arity-priority is not expressible per-word; G-041 no-silent-preference).
• punk::args::usage takes its options BEFORE the positional id ('usage -form X $id'; 'usage $id -form X' raises "Received more values than can be assigned") - caught by probe, worth knowing for future core consumers.

Verification evidence:

• Live probe matrix through bin/punk91 (args level, src mode) and the fake-main harness under bin/punk902z.exe tclsh (current core, no bake): narrowing by name and ordinal (P1/P2), formhint labels render unwrapped at piped default width for both multi-form defs, dry-run accept with Argument|Source|Value report (P3), reject exit 1 stdout-clean (P4), -encoding LIMIT diagnosis (P5), mixed-vintage witness block (P6, no src: baked 0.6.1 moduledoc served), passthrough ignored (P7), buildinfo reject (P8), PUNKBOOT_PLAIN plain twin (P9), ./oneliner collision dodge (P10), 'help script file' narrows to the file form (P11), 'help help tclsh' clone render (P12).
• launcherhelp.test 38/38 on tclsh90 AND tclsh87: 25 existing pins unchanged (the two direct-kit trailing-word pins re-described as VINTAGE-PROOF - their assertions hold under both the historic core and the depth core, whatever the kit's bake vintage) + 13 new G-170 pins: narrow by formname/ordinal, formhint labels, dry-run accept (form + report), reject, -encoding LIMIT, collision dodge, passthrough ignored, buildinfo reject, registration parse=1 accept/reject parity (same words as the dispatch-half pins launcherhelp_registration_parse_pass/_reject), vintage witness, plain degraded tail.
• args subtree 337 passed / 3 pre-existing skips / 0 failed on BOTH runtimes (punkexemodel/formcheck/docpackages/formhint pins unaffected); punkexe subtree at the recorded baseline on both runtimes (152/4/10 - the 10 failures are the recorded pre-existing maketclbakelist(2)/ maketcllibfetch(8) set, G-139 pending user decision; maketclhelp 12/12 and scriptexec 27/27 green - make.tcl surfaces and app behaviour untouched).
• Minted punkexe-0.9.0.tm via make.tcl modules (mint tree; not committed - gitignored by design). Kits/bootsupport/vfscommon remain stale until the user-owned promotion + bake.

Follow-ons

Follow-on: coherent-set promotion - the same vfscommonupdate/bake event as G-169's open promotion line, now additionally carrying punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + app-punkscript 1.3 (with punk::args 0.18.0 + punk::ansi 0.2.0 for the landing report); mixed intermediate states degrade gracefully by construction (fence witness, guarded parse_report) => landed 2026-08-06 (promotion + bake: bootsupport punk::args 0.18.0 + punk::ansi 0.2.0; _vfscommon.vfs punkboot core 0.7.0 + punkexe moduledoc 0.9.0 + punkboot moduledoc 0.3.1 + app-punkscript 1.3; 11 kits rebaked and deployed - the deployed kit now serves narrowing, formhint labels and the parse_report dry-run, and the tclsh fence witness is satisfied so its dry-run is live instead of the historic ignored-tail render) Follow-on: punkboot moduledoc registration guidance - note at the 'argsid' key that a multi-form project definition may carry its own '@cmd -formhint " help _{%formname%"' template now that the launcher narrows on form words (project parse=1 dry-run and narrowing already work; only the authoring hint is missing) => open}