Goals: draft G-149/G-150/G-151 (user-approved proposals)

G-149 punk::args configurable multi-form synopsis hint labels (the
hard-coded ' i -form N ...' column, repl-centric and unreachable for
(script) ids - identified during G-143).
G-150 punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash
declaration (-regexprefail {^-} on the plain name value - the verified
fix for the latent 'Ambiguous arguments' on bare parse-withid; brings
the make.tcl help dry-run contract to 'i').
G-151 punk::args annotated success render (received-args landing
report - the punk::args-level supersession of make.tcl's interim
'dry-run: line accepted' line).

All proposed status; overlap surveys recorded per goal (punkargs family
via goals_xref; G-044/G-050/G-056 named as related, G-149<->G-151
cross-linked). goals_lint clean.

Assisted-by: harness=claude; primary-model=claude-opus-5[1m]; api-location=anthropic.com

GOALS.md

@@ -406,3 +406,15 @@ Detail: goals/G-147-libfetch-revision-check.md
 Scope: src/modules/punk/mix/ (vendor-sync command surface - discovery beside the G-065 sync); punkproject.toml or sibling vendor manifest (G-065 declaration schema as consumed); src/tests/modules/punk/mix/ (discovery testsuite with local fixture upstreams)
 Detail: goals/G-148-vendor-upstream-discovery.md
 
+### G-149 [proposed] punk::args: configurable multi-form synopsis hint labels
+Scope: src/modules/punk/args-999999.0a1.0.tm (usage/arg_error multi-form Synopsis hint column); src/tests/modules/punk/args/testsuites/args/
+Detail: goals/G-149-punkargs-formhint-labels.md
+
+### G-150 [proposed] punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration
+Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins)
+Detail: goals/G-150-cmdhelp-form-narrowing.md
+
+### G-151 [proposed] punk::args annotated success render (received-args landing report)
+Scope: src/modules/punk/args-999999.0a1.0.tm (parse-result presentation); src/tests/modules/punk/args/testsuites/args/
+Detail: goals/G-151-punkargs-annotated-success-render.md
+

goals/G-149-punkargs-formhint-labels.md

@@ -0,0 +1,18 @@
+# G-149 punk::args: configurable multi-form synopsis hint labels
+
+Status: proposed
+Scope: src/modules/punk/args-999999.0a1.0.tm (usage/arg_error multi-form Synopsis hint column); src/tests/modules/punk/args/testsuites/args/
+Goal: The per-form hint labels rendered beside a multi-form definition's Synopsis lines (hard-coded ' i -form N ...' today) are configurable - a definition or rendering caller can supply its own hint text (parameterized by form index/name) or suppress the column - so consumers whose users cannot type 'i' (script-level definitions like make.tcl's, whose (script) ids are unreachable from any repl) show an actionable hint, while unconfigured definitions keep the current repl-oriented default.
+Acceptance: a punk::args mechanism (definition directive and/or usage/arg_error caller option) replaces the ' i -form N ...' hint labels with caller-supplied text and can suppress the column entirely; unconfigured definitions render byte-identical to today (existing synopsis/usage/arg_error pins pass unchanged); the mechanism is pinned in the args testsuite. make.tcl adopting it (e.g a 'make.tcl help tool <action>' phrasing) is recorded as consumer follow-through after a bootsupport promotion, not part of this acceptance.
+
+## Context
+
+Identified during G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md): multi-form usage tables render ' i -form N ...' beside each form's synopsis line, hard-coded in the renderer (bootsupport args-0.13.0.tm ~5475; same code in the dev module). The wording is repl-centric and doubly inapplicable in make.tcl output - 'i' is not a make.tcl surface, and (script)-scoped ids exist only inside a running make.tcl process, so no repl can address them. make.tcl meanwhile has its own per-form navigation the hint could name ('make.tcl help <subcommand> <action>' - G-143's dry-run help).
+
+## Notes
+
+- Related: G-050 (proposed) - synopsis argument-validity marking; same renderer surface, independent mechanism.
+- Related: G-056 (proposed) - display-time word wrapping for help content; sibling render-surface work.
+- Related: G-151 (proposed) - annotated success render; sibling punk::args render-surface goal drafted the same session.
+- Origin: G-144 (achieved 2026-08-01 - goals/archive/G-144-punkargs-synopsis-name-fallback.md) shipped the @cmd -name auto-synopsis lines these hints sit beside.
+- Overlap survey 2026-08-02: goals_xref paths src/modules/punk/args-999999.0a1.0.tm - the punkargs family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088); besides those named above the family entries are parser/spec mechanisms unrelated to the hint column. Consumer side: make.tcl's argdoc (src/AGENTS.md make.tcl bullet) after a bootsupport promotion.

goals/G-150-cmdhelp-form-narrowing.md

@@ -0,0 +1,17 @@
+# G-150 punk::ns cmdhelp form narrowing + selection-sound auto_exec::hash declaration
+
+Status: proposed
+Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdhelp); src/modules/punk/auto_exec-999999.0a1.0.tm (hash definition); src/tests/modules/punk/ns/testsuites/ (cmdhelp + auto_exec pins)
+Goal: 'i <command> ?word ...?' (punk::ns::cmdhelp) narrows a flat multi-form command to the form its trailing words select - punk::args form auto-selection, with the whole-command render retained when no form is selectable (no words, option-first lines, ambiguity) - and punk::auto_exec::hash's definition is selection-sound so it exemplifies the mechanism: a flag-led line selects its flag form uniquely instead of today's 'Ambiguous arguments' outcome on a bare parse-withid.
+Acceptance: 'i ::punk::auto_exec::hash -r' renders only the rehash form's usage and 'i ::punk::auto_exec::hash -d <name>' only the delete form, driven by the definition (no hash-handler involvement); hash's plain name value carries a flag-excluding constraint (-regexprefail {^-} or equivalent) such that bare punk::args::parse withid selects flag-led forms uniquely, with hash's runtime behaviour otherwise unchanged (a name literally starting with '-' now requires explicit -form selection - the accepted cost); ensembles, single-form commands and no-word invocations render as today (existing cmdhelp behaviour pinned unchanged); the behaviours are pinned in the module testsuites.
+
+## Context
+
+From the G-143 finalisation sessions (2026-08-01/02 - archived detail file's Progress notes): cmdhelp tolerates trailing argument words but performs no form narrowing on flat multi-form commands (verified live: 'i punk::auto_exec::hash -t' renders the whole-command help), while make.tcl help gained a dry-run contract that narrows via the same punk::args declarations. Probes verified punk::args honours per-arg -regexprepass/-regexprefail during form matching: with '-regexprefail {^-}' on a plain string value, a flag-led line selects the flag form uniquely; without it, hash's show_or_set form swallows flag-like words as name values and a bare parse-withid reports 'Ambiguous arguments ... match more than one form: show_or_set, rehash'. hash's handler pre-dispatches around this at runtime, so the defect is latent - it blocks exactly the declaration-driven consumers this goal adds.
+
+## Notes
+
+- Related: G-044 (proposed) - punk::args-driven interactive completion; form narrowing and completion share the words-to-candidate-forms machinery (see also the noformmatch classes finding recorded in goals/archive/G-143-maketcl-multiform-help.md).
+- Related: G-050 (proposed) - punk::ns::synopsis validity marking; sibling punk::ns presentation surface.
+- Related: G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md) - the make.tcl help dry-run contract this mirrors at the repl.
+- Overlap survey 2026-08-02: goals_xref paths src/modules/punk/ns-999999.0a1.0.tm src/modules/punk/auto_exec-999999.0a1.0.tm - ns family G-044 G-050 G-052 G-075 G-085 (G-052 autodef docs and G-085 cmdtrace are unrelated mechanisms; G-075 package-id docs tangential); no auto_exec-scoped goals surfaced.

goals/G-151-punkargs-annotated-success-render.md

@@ -0,0 +1,17 @@
+# G-151 punk::args annotated success render (received-args landing report)
+
+Status: proposed
+Scope: src/modules/punk/args-999999.0a1.0.tm (parse-result presentation); src/tests/modules/punk/args/testsuites/args/
+Goal: punk::args can render a SUCCESSFUL parse the way arg_error renders a failed one - the usage table (or a compact per-argument report) annotated with where each received word landed: options consumed, values attributed to the argument that took them, received distinguished from defaulted - so dry-run consumers (make.tcl help today; completion/hinting later) present authoritative landing information instead of hand-assembled summaries.
+Acceptance: given a successful parse result (or the words plus definition id), a punk::args surface renders per-argument received-vs-default annotation covering leaders, opts and values including -multiple aggregation - the canonical demonstration being a flag-like word consumed as a VALUE (the 'punk91 -confirm 0'-as-three-values class) visibly attributed to its consuming argument; failure-side rendering is unchanged (existing arg_error pins pass); the behaviour is pinned in the args testsuite. make.tcl retiring its interim one-line 'dry-run: line accepted ...' report in favour of this render is recorded as consumer follow-through after a bootsupport promotion, not part of this acceptance.
+
+## Context
+
+From the G-143 dry-run help sessions (2026-08-01/02 - archived detail file): the failure side has arg_error's annotated tables, but a successful dry-run had nothing showing where the supplied words landed, so make.tcl grew an interim one-line report built from the parse result's 'received' key ('dry-run: line accepted (form build) - action = build | -test = 0 | toolname = punkzip'; before bake kitnames became choice-restricted, the value-swallow clue read 'kitname = punk91 -confirm 0'). The parse result already carries received/leaders/opts/values/multis - this goal is a presentation surface over existing data, at punk::args level where every consumer (and the repl) can share it.
+
+## Notes
+
+- Related: G-050 (proposed) - synopsis argument-validity marking; the nearest sibling (status-aware marking over the same argument rows).
+- Related: G-044 (proposed) - punk::args-driven completion; landing attribution is the same data completion hints from.
+- Related: G-149 (proposed) - configurable form-hint labels; sibling punk::args render-surface goal drafted the same session.
+- Overlap survey 2026-08-02: goals_xref paths src/modules/punk/args-999999.0a1.0.tm - the punkargs family as recorded in G-149's survey; G-050 (named above) is the closest surface, the remainder are parser/spec mechanisms.