The per-form hint labels rendered beside a multi-form definition's
synopsis lines in the usage/arg_error table (hard-coded ' i -form N
...' previously) are now a template substituted per form: %formindex%
is replaced with the form's 0-based ordinal, %formname% with its name,
and an empty template suppresses the labels entirely (the cell keeps
just the Synopsis: label, as single-form renders always have). Both
acceptance arms landed. Definition side: new '@cmd -formhint
<template>' key - rides the existing arbitrary-key cmd_info merge (no
resolver change), round-trips through resolved_def, not display
-deferred; documented in the define -help directive-options. Caller
side: new -formhint option on arg_error (manual parser + PUNKARGS
block) pulled into usage via its existing resolved_def opts pull;
supplied-empty (suppress) is distinct from not-supplied (the option
declares no -default, so an unsupplied usage call passes nothing
through). Precedence: caller > definition > built-in default, whose
template substitutes to the exact prior bytes. Motivation (G-143
origin): script-level (script) ids - make.tcl's - are unreachable from
any repl, so the repl-oriented 'i' hint was not actionable there.
Scope decisions pinned: single-form renders never carry hint labels;
the -return string renderer has no hint column and is unchanged.
Byte-identity for unconfigured definitions proven by pre/post capture
diff of 'punk::args::usage ::punk::args::parse' (identical bytes,
through the usage pass-through path). Tests: new formhint.test (9
tests - default labels, directive/caller/suppression matrix, parse
-error path, single-form + string-renderer scope); full punk/args
subtree 302/0-fail on BOTH tclsh90 9.0.3 and the punk86 kit (8.6);
punk/ns subtree 115/115 (cmdhelp consumer). make.tcl help untouched
until promotion (maketclhelp.test still pins the bootsupport hint).
Goals: G-149 activated at user direction then flipped achieved
2026-08-05 + archived (index record newest-first, detail file to
goals/archive with Progress evidence and 1 follow-on: make.tcl
adoption after a bootsupport promotion => open). Activation-freshness
survey recorded the G-167 relationship (same renderer surface -
composition note both sides); reference sweep updated G-151/G-167
mentions; goals_lint clean, no orphaned xref pairs. punkshell 0.55.0 +
CHANGELOG. Bootsupport/vfscommon snapshots unchanged until promotion +
bake.
Claude-Session: https://claude.ai/code/session_01QgaxV27VZkmEec7oNbEVFc
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
