# G-050 punk::ns::synopsis argument-validity marking and status-aware returns

Status: proposed
Scope: src/modules/punk/ns-999999.0a1.0.tm (synopsis), src/modules/punk/args-999999.0a1.0.tm (synopsis renderer), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (synopsis pins)
Goal: synopsis ('s') marks supplied argument words for validity the way cmdhelp's usage display does (goodarg/badarg styles via the G-049 parse-status structure), offers the same status machine-parsably in its dict return, and replaces the curried-alias excess-args length arithmetic (the 's pse' REVIEW note) with a parse against the resolved definition.
Acceptance: 's <cmd> <valid args>' renders the supplied words marked as validated and 's <cmd> <invalid args>' marks the offending word, while output with no argument words supplied is unchanged (the synopsis_GAP_no_argument_validity_marking pin flips); the dict return carries per-argument status; the curried-alias substitution behaviour (synopsis_curried_alias_shows_braced_target pin) is resolved to a documented presentation derived from parsing rather than list-length arithmetic; existing synopsis output tests (args testsuite synopsis.test and test::punk::args) pass; depends on G-049 for the status structure; G-044's completion/hint display is a consumer of the same status API (cross-reference, not a dependency).

## Context

'i <cmd> <args...>' (cmdhelp) marks supplied argument words for validity; 's <cmd>
<args...>' (synopsis) does not - its output is identical whether the trailing words are
valid, invalid or absent (pinned 2026-07-10: synopsis_GAP_no_argument_validity_marking).
The user-facing intent is parity: the synopsis line(s) should show which supplied words
validated (goodarg style) and where the first problem is (badarg style), with the same
info/error scheme signalling as the usage table.

Separately, synopsis's handling of curried aliases is length-arithmetic based: the
`excess` computation (ns-999999.0a1.0.tm, "This isn't quite right.. e.g see: s pse"
REVIEW comment) counts args_remaining vs supplied words and lreplaces that many leading
synopsis words with resolved_args. For a curried alias the substituted command renders
as the braced alias target (e.g `{::ns::realcmd curriedarg} ...`) rather than the alias
name (pinned: synopsis_curried_alias_shows_braced_target).

## Approach

Consume the G-049 parse-status structure: parse the trailing words against the resolved
definition (same docid resolution as cmdhelp via cmdinfo), then render the synopsis with
per-word marking derived from the status, and expose the status in the dict return.
Replacing the excess-args arithmetic with an actual parse against the resolved definition
is the same change - the parse knows how many words the definition consumed and how the
curried words map onto leaders.

Also worth addressing while in there: the existing in-source note that treating the
synopsis line as a Tcl list for lreplace is risky with ANSI content ("todo - consider
always using 'punk::args::synopsis -return dict' and operating on that list to rebuild
string").

## Notes

- Depends on G-049 (status structure) - satisfied: achieved 2026-07-10, see goals/archive/G-049-punkargs-parse-status-model.md. G-044's hint display is a future consumer of the
  same API - keep the marking function reusable outside synopsis/cmdhelp rendering.
- Existing string-shape tests: args testsuite synopsis.test and the installed
  test::punk::args synopsis tests ("must be no leading space" convention) - marking must
  be ANSI-only so ansistripped output stays stable, or those tests get a documented
  update.