punkshell/goals/archive/G-144-punkargs-synopsis-name-fallback.md

G-144 punk::args auto-synopsis: @cmd -name fallback for non-command ids

Status: achieved 2026-08-01 Scope: src/modules/punk/args-999999.0a1.0.tm (synopsis renderer + usage/arg_error synopsis display); src/tests/modules/punk/args/testsuites/args/ (synopsis pins) Goal: Auto-generated synopses render their invocation name from @cmd -name whenever the definition id is not the command's invocation name (script-level ids like (script)::punkboot::modules and (shared)/(package)-style doc ids), falling back to the id only when no @cmd -name is declared - so consumers get the automatic bracket-notation synopsis with the real command name, and explicit @form -synopsis overrides become optional rather than mandatory for such ids. Acceptance: a definition with @id -id (script):❌:sub and @cmd -name 'make.tcl sub' auto-renders synopsis lines beginning 'make.tcl sub' across the punk::args::synopsis, usage and arg_error surfaces (table and string renderers), with every form line of a multi-form definition carrying the name; definitions whose id equals the invocation name render byte-identical to today (existing synopsis/usage/arg_error suites pass unchanged apart from deliberately updated pins); a definition with neither a command-path id nor @cmd -name renders the id as today; the new behaviour is pinned in the args testsuite.

Context

The synopsis generator produces the preferred bracket-notation lines but names the definition id verbatim: verified 2026-08-01 on punk::args 0.12.7 - '(script)::toy::flat [-test ] [toolname]...'. For script-level definitions (make.tcl's (script)::punkboot::_{) and shared/package doc ids, that forced the explicit @form -synopsis workaround adopted in G-030 and documented in G-045's authoring ergonomics; make.tcl hand-writes Tcl-style ?...? synopses for this reason alone, while the user-preferred style is the automatic punk::args bracket notation.}

Approach

• Display-only change: parsing, ids, get_spec and spec caching are untouched.
• Rule settled in the work (2026-08-01): the fallback is gated on the (script) prefix only - the one constructed-id family whose @cmd -name is by convention the invocation name. See Notes for the prefix-family survey behind the choice. Hard constraint held: existing real-command definitions (id == command path) render byte-identical (full args testsuite passes with no pin updates).
• Consumer follow-through: make.tcl drops its per-definition @form -synopsis lines once this ships (under G-143 if active, else a small follow-on edit).

Notes

• Origin: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) recorded the id-vs-name synopsis finding and mooted this exact nicety; G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md) documents the explicit @form -synopsis lesson this retires for constructed/script ids.
• Related: G-050 (proposed) - synopsis validity marking; same renderer surface, independent mechanism.
• Related: G-056 (proposed) - display-time help wrapping; same renderer file, independent mechanism.
• Related: G-143 (sibling proposal) - make.tcl consumer of the fallback (auto bracket-notation synopses).
• Overlap survey 2026-08-01: goals_xref paths src/modules/punk/args-999999.0a1.0.tm lists 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 G-050/G-056 named above, these target parser/spec mechanisms, not synopsis name display.
• Activation freshness re-run 2026-08-01 (goals_xref score G-144): no new related goals since drafting - the strongest unlinked pair is G-055 (0.68, tclcore regen; its ids are real command paths, untouched by the fallback), and the one-directional punkargs-family pairs are all parser/spec mechanisms already covered by the drafting survey. No new Related lines required.

Prefix-family survey (2026-08-01, the settled rule's basis)

Every parenthesised id family in-tree was inventoried and probed for its @cmd -name convention:

• (script) - script-level dispatch surfaces: (script)::punkboot::* (make.tcl), (script)::punkexe::* (punkexe moduledoc), (script)::runtests, (script)::runtestmodules, (script)punkargs. Every one carries an invocation-style @cmd -name ("make.tcl modules", "punkexe tclsh", "runtests", ...). The id names a namespace inside the script's dispatch, not the invocation. FALLBACK APPLIES (the goal's core case).
• (autodef) - generated by punk::ns::generate_autodef from REAL commands. id-minus-tag IS the invocation name; arg_error's existing tag strip (args-999999.0a1.0.tm, the (autodef)* match in the synopsis section) already surfaces it. The @cmd -name is a display LABEL, not an invocation: "(autodef) destroy" has -name "destroy"; "(autodef)" has -name "Object: ::x"; only new/create/method autodefs carry -name == id-minus-tag. Rendering the label would regress the usage display (probe: 'destroy' / 'Object: ::toy::obj method...' instead of '::toy::obj destroy' / '::toy::obj method...'). EXCLUDED - behaviour preserved byte-identical (pinned).
• (shared) - shared doc fragments: (shared)::package carries NO @cmd -name (falls back to the id, per the acceptance's third clause); (shared)::namespace ensemble carries a prose label ("shared definition namespace ensemble create/configure"). EXCLUDED.
• (package) / (default) - package-level / tclcore default doc ids: no @cmd -name at all ((package) uses @package -name). Fallback would be a no-op. EXCLUDED.
• (widgetcommand) - tkcore moduledoc: -name is either the id echoed or a decorated label ("Tk widget: (widgetcommand)Class_Button"). EXCLUDED.

The goal text named "(shared)/(package)-style doc ids" alongside (script) as beneficiaries; the survey shows those families declare no invocation-style -name today, so the (script)-only gate satisfies the goal's intent with zero collateral rendering change. If another family later adopts invocation-style -name conventions, the gate widens by extending the prefix match in punk::args::synopsis. User flagged pre-implementation that the goal under-considered (autodef) vs (script) - the survey above is the consideration record.

Progress

• 2026-08-01 (landed): punk::args 0.13.0 - the auto-synopsis name fallback in punk::args::synopsis (formline + summary path; usage/arg_error inherit through their per-form synopsis calls). Doc updates in-module (@form -synopsis directive known-case text, synopsis -help) and in src/modules/AGENTS.md (authoring ergonomics bullet). Six new pins in src/tests/modules/punk/args/testsuites/args/synopsis.test: (script) full/summary, multi-form name-on-every-form-line, usage/arg_error/table surfaces, no-name constructed id renders id, (autodef) unchanged, real-command id byte-identical.
• Verification: synopsis.test 22/22; full modules/punk/args/*** + modules/punk/ns/*** suites green apart from two PRE-EXISTING nsprimitives.test failures (nseval_ifexists_weird, nstree_raw_pins - weird colon-run namespace handling, fail identically with the module change stashed; unrelated). tcl87 runner. make.tcl modules + bootsupport rebuilt (bootsupport snapshot now args-0.13.0.tm; the run also propagated two lagging source bumps - commandset::layout 0.2.0->0.3.0, commandset::project 0.4.0->0.4.1, and the shellfilter 0.2.4 G-145 comment - and pruned the superseded copies). 'make.tcl help modules' renders unchanged (explicit @form -synopsis overrides still win). Project version 0.39.5 -> 0.39.6 (patch: latent capability, no currently-shipped definition renders differently).
• Remaining for acceptance: none - the Acceptance clauses are all met and pinned. Achieved 2026-08-01: the user confirmed the settled (script)-only gate against the Goal statement's (shared)/(package) mention (the survey shows those families declare no invocation-style -name today, so there is nothing to render differently; widening later is a one-line prefix-match extension in punk::args::synopsis).
• Follow-on (not part of this goal's acceptance): make.tcl drops its per-definition @form -synopsis overrides - under G-143 if active, else a small follow-on edit; the punkexe moduledoc's six overrides are the same candidate set.