punkshell/goals/G-143-maketcl-multiform-help.md

G-143 make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage

Status: proposed Scope: src/make.tcl (::punkboot::argdoc definitions + help dispatch); src/tests/shell/testsuites/punkexe/ (new piped help characterization test) Goal: The tool and buildsuite subcommands are declared as multi-form punk::args definitions (one @form per action with a literal action leader and per-form opts/values) so that full-subcommand help renders one synopsis line per action - making it explicit which actions accept and -test where today's single line conflates them - 'make.tcl help ' renders that action's single-form usage, tool dispatch parses through the definition (pointed punk::args usage errors for unknown actions and flags), and buildsuite keeps its passthrough driver-args contract (forms serve its help/synopsis accuracy only). Acceptance: 'make.tcl help tool' shows per-action synopsis lines (list; info; build with -test and toolnames; test with toolnames) instead of the single conflated line; 'make.tcl help tool build' and 'make.tcl help buildsuite build' render that form's usage table and an unknown action subject produces a punk::args usage error (exit 1); all currently-working tool invocations behave unchanged while 'make.tcl tool ' and unknown flags produce punk::args usage errors (exit 1); buildsuite driver-arg forwarding is unchanged (an arbitrary flag after 'buildsuite build ' still reaches the driver untouched); PUNKBOOT_PLAIN=1 degraded dispatch still handles the same invocations via the plain scan; the behaviours are pinned by a piped characterization test under src/tests/shell/testsuites/punkexe/.

Context

G-030 (achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md) made make.tcl the punk::args showcase, but its tool/buildsuite definitions document the action surface as one line ('make.tcl tool list|info|build|test ? ...? ?-test 0|1?') that cannot say which optionals belong to which action, and 'make.tcl help tool list' is not supported - identified as underspecification of the showcase intent (user review 2026-08-01). The punk shell's 'i' (punk::ns::cmdhelp) renders per-form usage for exactly this shape; make.tcl should showcase the same depth.

Approach

• Mechanisms verified live on bootsupport punk::args 0.12.7 (2026-08-01): @form sections with 'action -type literal()' leaders render per-action synopses; punk::args::usage -form renders a single-form table (@cmd -name in the COMMAND header); punk::args::parse auto-selects the form from the literal action word (result dict carries form/formstatus). In-tree exemplar: punk::auto_exec::hash (multi-form definition + handler form dispatch).
• help dispatch: the help subject gains an optional trailing action word mapped to usage -form; ' -help' can route the same way.
• tool becomes fully declared (its argument surface is a closed set); buildsuite build's trailing driver args stay a -type any -multiple passthrough (arbitrary driver flags must not be parsed as options).
• Definitions follow the braced -&/tstr argdoc house style (G-045 mechanisms - see src/modules/AGENTS.md "punk::args definition authoring ergonomics").
• Same degrade contract as the existing argdoc block (guarded defines + get_spec probes; the plain fallback keeps today's passthrough behaviour).

Notes

• Related: G-144 (sibling proposal) - auto-synopsis @cmd -name fallback; until it ships, per-form synopsis lines are hand-written (@form -synopsis, bracket notation preferred) or would display definition ids.
• Related: G-025 (proposed) - the future version-report subcommand should be born to these conventions (carried from G-030's notes).
• Overlap survey 2026-08-01: goals_xref paths src/make.tcl scores no intersects (make.tcl is a df-damped ubiquitous anchor); manual index sweep - the live make.tcl-scoped goals (G-005 G-006 G-012 G-019 G-023 G-026 G-027 G-028 G-029 G-063 G-065 G-067) are build/vendor mechanics with no help/dispatch overlap; punkexe-test-scoped goals (G-077 G-131 G-141) unrelated.
• Archived-goal references in this file: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md); G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md); G-104 achieved 2026-07-25 (goals/archive/G-104-maketcl-buildsuite-surface.md) - buildsuite surface whose passthrough contract this preserves; G-126 achieved 2026-07-27 (goals/archive/G-126-punkzip-accelerator.md) - origin of the tool subcommand.