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

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

Status: achieved 2026-08-01 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 (achieved 2026-08-01 - see goals/archive/G-144-punkargs-synopsis-name-fallback.md) - auto-synopsis @cmd -name fallback shipped in punk::args 0.13.0: (script)-prefixed ids now auto-render per-form synopsis lines with the declared @cmd -name in bracket notation, so this goal's multi-form definitions need no @form -synopsis overrides for the name, and make.tcl's existing hand-written overrides become optional (G-144 recorded their retirement as this goal's consumer follow-through, or a small standalone edit if this goal is not active).
• 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.
• Activation freshness re-run 2026-08-01 (goals_xref score G-143): no new related goals since drafting - the strongest unlinked pairs (G-085 argdoc key, G-021/G-108 test key, G-083/G-072/G-075/G-055/G-053 punkargs term noise) are unrelated mechanisms; G-077's one-directional pair was already named in the drafting survey. No new Related lines required.
• 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.

Progress

• 2026-08-01 (activation session): multi-form tool/buildsuite/help definitions (single-choice action leaders + -choicelabels, per-form opts/values), tool dispatch parse-through, help subject+action routing ('help _{' and ' -help'), degraded-mode preservation, and the piped characterization coverage (new maketclhelp.test; maketcltool.test unknown-action pin updated to the exit-1 punk::args surface) landed in the working tree.}
• 2026-08-01 (finalisation session): user-approved acceptance deviation recorded - the historic tool flag-anywhere argument order is NOT preserved: the declared positional model is options-before-names ('make.tcl tool build -test 0 ...', matching bake's flags-before-names convention), with docs/agent guidance updated to match (src/AGENTS.md make.tcl bullet; gethelp + HELPTEXTS + tool-list footer + degraded usage line; flag-shaped tool names earn a stderr hint at exit 2). The PUNKBOOT_PLAIN degraded handler keeps the historic flag-anywhere manual parse and exit-2 surface. help action resolution additionally accepts a 0-based form index ('make.tcl help tool 2' renders byte-identically to 'help tool build') - the notation of the rendered ' i -form N ...' hints and of punk::args's own -form error text; out-of-range indexes exit 1 with the punk::args -form error. G-144 consumer follow-through applied: all 17 per-subcommand @form -synopsis overrides retired (automatic @cmd -name bracket-notation synopses; per-subcommand help output captured before/after and diffed - synopsis-line notation changes only, no information lost; check/projectversion/workflow render byte-identical); the top-level 'make.tcl ?subcommand? ?flags?' override is deliberately kept (states the bare-invocation and per-subcommand-flags reality the auto render cannot).
• 2026-08-01 (same-day post-flip refinement, user-directed): the '?action?' subject-plus-action-word help interface (and its numeric form-index variant) was reshaped to the user's intended contract - 'make.tcl help ?arg ...?' accepts the subcommand's own COMMAND LINE ('help tool build -test 0 punkzip'), with the leading action word narrowing multi-form subjects, later words tolerated/ignored, option-first lines falling back to whole-subcommand usage, and single-form subjects ignoring the words; the numeric form index was withdrawn as unintuitive (exit 1 like any unknown action word). Probe recorded: the repl 'i' (punk::ns::cmdhelp) tolerates trailing argument words but does NOT form-narrow flat multi-form commands (verified on punk::auto_exec::hash) - make.tcl help now exceeds it there. Shipped as punkshell 0.40.1; maketclhelp.test pins updated (12 tests). Superseded same day by 0.40.2 (below).
• 2026-08-01 (second same-day refinement, user-directed): help is now a full DRY-RUN - the words parse through the subject's declaration via punk::args form auto-selection exactly as dispatch would parse them; accepted lines render the matched form's usage, rejected lines emit the subcommand's own punk::args noformmatch diagnosis (all-forms synopsis + per-form reasons, stderr, exit 1), with one carve-out: a BARE action word/prefix renders its form directly since forms with required values ('buildsuite build' needs a suitename) would fail a strict dry-run - the 0.40.1 leading-word-only selection and its option-first whole-usage fallback are superseded (the parse error table is itself usage documentation, and help verdicts mirror dispatch verdicts exactly). Empirical punk::args facts recorded from the probes: flag-like words at/after the first value position are consumed as VALUES (so 'bake punk91 -confirm 0' and 'tool build -test' PARSE, swallowing the flag-like word - only leader-level mistakes and option-position unknowns fail); per-arg -regexprepass/-regexprefail ARE honoured during form matching, so '-regexprefail {^-}' on a plain string value makes a flag-led line select the flag form uniquely (verified: without it 'Ambiguous arguments ... match more than one form'; punk::auto_exec::hash exhibits exactly this on bare parse withid, its handler pre-dispatching around it) - candidate fixes for auto_exec/cmdhelp narrowing noted to the user, not applied here.
• Verification at flip (2026-08-01, native tclsh90): runtests shell/testsuites/punkexe full subtree 114 tests / 110 pass / 4 env-gated skips / 0 fail, including maketclhelp.test 12/12 (per-action synopses, form tables incl. the form-index pin, exit-1 unknown action/flag errors, 'tool build -help' route, buildsuite -bogusxyz driver forwarding, PUNKBOOT_PLAIN degrade) and maketcltool.test 4/4. Kit-hosted punk-exe rendering shows raw (script) ids until the next routine vfscommonupdate+bake refreshes the kit's preloaded punk::args past 0.13.0 (documented in the test header; dispatch surfaces pinned kit-hosted in maketcltool.test are name-independent).