G-041 achieved: multi-form matching - automated form selection for parsing and documentation

Acceptance reviewed clause-by-clause in the detail file: auto-selection
on a unique clean match (forms.test GAPs flipped), candidate-naming
noformmatch/multipleformmatches errors, -form list restriction across
get_dict/parse/parse_status/arg_error, doc surface presenting the
best-matching form(s) ('i after cancel <id>' presents the cancel form;
's after cancel someid' underlines the matching synopsis lines),
explicit single -form unchanged, full punk::args/punk::ns suites pass
(full tree 822/836 with only the exec-14.3 baseline failure).

Flip edits: index entry to GOALS-archive.md (achieved 2026-07-13),
detail Status flipped with acceptance review and live-verification
record, reference sweep updates G-044 (candidacy API now available -
parse_status formstatus), G-055 backlink, G-072 backlink. Detail-file
move to goals/archive/ follows as a pure rename; goals_lint transiently
unclean between the two commits.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

GOALS-archive.md

@@ -46,6 +46,9 @@ Acceptance: a documented procedure reproduces the spin on the current kit (e.g.
 Scope: src/modules/punk/args-999999.0a1.0.tm (parse + usage rendering), src/modules/punk/ns-999999.0a1.0.tm (cmdinfo/cmd_traverse choice resolution parity), src/modules/punk-999999.0a1.0.tm (punk::help topic argdoc as first consumer), src/tests/modules/punk/args/testsuites/, src/tests/modules/punk/ns/testsuites/
 Acceptance: a definition using -choicealiases parses an alias (and an alias prefix where -choiceprefix allows) to its canonical choice in the parse result, with -choicerestricted 0 passthrough and the deny/reserve lists honoured unchanged; usage display shows one entry per canonical choice with aliases folded (no duplicate rows; -choicelabels attach to the canonical); punk::ns::cmdinfo/cmd_traverse resolve subcommand words to docids with the same outcome as the parser for alias, prefix, denied, reserved and unknown words (the pre-goal characterization tests updated from pinned-GAP to fixed); punk::help's topic definition adopts the feature so `i help` lists one entry per registered topic while `help h`/`help e` still fall through to command lookup; definitions without -choicealiases behave unchanged (existing punk::args and punk::ns suites pass).
 
+### G-041 [achieved 2026-07-13] punk::args multi-form matching: automated form selection for parsing and documentation → detail: goals/archive/G-041-punkargs-form-matching.md
+Scope: src/modules/punk/args-999999.0a1.0.tm (parse form selection, arg_error/usage form marking), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/synopsis closest-form indication), src/tests/modules/punk/args/testsuites/
+
 ### G-045 [achieved 2026-07-12] punk::args definition authoring ergonomics: record continuation, @cmd unindented fields, constructed-definition normalization → detail: goals/archive/G-045-punkargs-authoring-ergonomics.md
 Scope: src/modules/punk/args-999999.0a1.0.tm (record parsing in resolve, tstr interplay, arg_error @cmd rendering), src/tests/modules/punk/args/testsuites/ (rendering.test/defquoting.test as the safety net), src/modules/punk-999999.0a1.0.tm (::punk::helptopic::define_docs de-hacked as the consumer proof)
 Acceptance: a definition using the chosen record-continuation mechanism parses identically to its backslash-continuation equivalent (existing definitions unchanged - continuation is additive), with the token's collision rules documented and an escape/rejection story for values that legitimately match it; @cmd -help/-summary honour -unindentedfields (the rendering.test GAP rendering_unindentedfields_cmd_help_GAP flips to aligned); a constructed definition can request whole-block normalization so embedded continuation indentation behaves as in file-style definitions (the rendering_constructed_def_indent_characterization expectations updated to the chosen semantics), and ::punk::helptopic::define_docs drops its manual pre-normalization to prove it; the quoting rules from defquoting.test appear in the punk::args::define -help documentation; the full punk::args suite (128 tests incl. the rendering invariants: nesting independence, relative-indent preservation) passes with GAP tests flipped, none weakened.

GOALS.md

@@ -194,10 +194,6 @@ Detail: goals/G-035-mixed-tm-pkgindex-provision.md
 Scope: src/lib/app-punkshell/punkshell.tcl (eof-restart handover), src/modules/punk/repl-999999.0a1.0.tm (eof-restart done-mode that skips codethread teardown), src/modules/punk/repl/codethread-999999.0a1.0.tm (as touched)
 Detail: goals/G-038-piped-session-continuity.md
 
-### G-041 [active] punk::args multi-form matching: automated form selection for parsing and documentation
-Scope: src/modules/punk/args-999999.0a1.0.tm (parse form selection, arg_error/usage form marking), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/synopsis closest-form indication), src/tests/modules/punk/args/testsuites/
-Detail: goals/G-041-punkargs-form-matching.md
-
 ### G-042 [proposed] Subshell-declared help topics via punk::config with defined shadowing policy
 Scope: src/modules/punk-999999.0a1.0.tm (::punk::helptopic registry), src/modules/punk/config-0.1.tm (stored declaration source), src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit hooks)
 Detail: goals/G-042-subshell-help-topics.md

goals/G-041-punkargs-form-matching.md

@@ -1,6 +1,6 @@
 # G-041 punk::args multi-form matching: automated form selection for parsing and documentation
 
-Status: active
+Status: achieved 2026-07-13
 Scope: src/modules/punk/args-999999.0a1.0.tm (parse form selection, arg_error/usage form marking), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/synopsis closest-form indication), src/tests/modules/punk/args/testsuites/
 Goal: for multi-form definitions punk::args determines which form(s) an argument list matches - parse without -form attempts all permitted forms instead of effectively form 0, -form accepts the documented list-of-forms restriction, and the documentation surface indicates the match ('i after cancel <id>' presents the cancel form; 's after cancel someid' marks the closest synopsis) - with explicit single-form restriction retained for callers that require it.
 Acceptance: parsing a multiform definition (after-like fixture) without -form succeeds when the args match exactly one form (the pinned GAP tests in forms.test flip to auto-selected results); an argument list matching no form (or several) produces an error naming the candidate forms rather than a form-0 type error; -form with a list of form names/indices restricts parsing to that subset (currently an 'Expected int 0-N or one of ...' error); 'i <cmd> <args...>' and synopsis output indicate the best-matching form(s) for supplied args; explicit -form <single-name-or-index> behaviour is unchanged; the full punk::args and punk::ns suites pass.
@@ -127,6 +127,39 @@ when shaping step 1.
     candidate (TIP 746 removes expr operand behaviour in 9.1 anyway).
   Suites: punk::args 198/199 (1 pre-existing skip), punk::ns 57/57, full source tree
   836 total / 822 passed / 13 skipped / 1 failed = exec-14.3 (the known baseline).
+- 2026-07-13 ACHIEVED - acceptance review against each clause:
+  - Multiform parse without -form succeeds on a unique clean match: the forms.test
+    GAP pins flipped to auto-selected results (forms_parse_autoselect - ms/cancel/
+    idle each selected from the words alone; forms_parse_autoselect_shared_prologue
+    covers arity-discriminated forms sharing a leader block).
+  - No-match/several-match errors name the candidate forms instead of a form-0 type
+    error: noformmatch carries every candidate's first-line failure ranked
+    best-first (forms_parse_noformmatch) and multipleformmatches names the matching
+    forms (forms_parse_multipleformmatches) - the 'several' outcome is an error by
+    recorded decision (no silent first-declared preference).
+  - -form list restriction: a list of names/indices restricts candidacy to the
+    subset across get_dict/parse/parse_status/arg_error
+    (forms_parse_formlist_restriction; unrecognised elements keep the invalid
+    -form error).
+  - Doc surface indicates the best-matching form(s): 'i after cancel <id>' presents
+    the cancel form's argument table (cmdhelp_multiform_autoselected_form_presented,
+    cmdhelp_multiform_noformmatch_best_candidate) and 's after cancel someid'
+    underlines the matching synopsis line(s)
+    (synopsis_multiform_marks_matching_form/_unmarked_without_args); live-verified
+    against the tclcore models on punk902z ('i lseq 0 10 2' range form underlined
+    info-scheme; 'i after cancel someid' ambiguity named with both cancel forms
+    marked).
+  - Explicit single -form behaviour unchanged: the pre-existing explicit-form tests
+    (forms_parse_explicit_form_by_name/_by_index) pass unmodified.
+  - Full punk::args and punk::ns suites pass (198/199 with 1 pre-existing skip;
+    57/57); full source tree 822/836 with the exec-14.3 baseline as the only
+    failure.
+  Adjacent extra: the @form -synopsis override GAP flipped
+  (forms_form_synopsis_override_rendered). The G-044 candidacy-API design note is
+  satisfied by parse_status's formstatus key (per-form compatibility on partial
+  arglists). Deferred as refinements (not acceptance): literal-discrimination
+  fast path for parse performance; affinity alignment through received options;
+  punk::args::synopsis -form list support (single-form restriction retained there).
 
 ## Alternatives considered
 

goals/G-044-repl-command-completion.md

@@ -40,9 +40,11 @@ arginfo principle: introspection must not run commands to elicit usage).
    position. Choice-word matching must reuse the parser's resolution rules (the shared
    choice-resolution helper from G-040 (achieved 2026-07-08) is the natural common code; prefix
    highlighting from the usage renderer already computes minimal prefixes).
-   Form handling: before G-041, enumerate all forms' next-position candidates (union)
+   Form handling: G-041 (achieved 2026-07-13) shipped the candidacy API this consumes
-   and show all/form-0 synopses with the limitation noted; when G-041's candidacy API
+   - punk::args::parse_status reports per-form compatibility for a (partial) argument
-   exists, rank/filter forms by the partial input (G-041's detail file notes the API
+   list in its formstatus key (status valid|incomplete|invalid per form; the form key
+   is the matched/best-candidate form) - rank/filter forms by the partial input with
+   it (G-041's detail file notes the API
    should accept partial argument lists for exactly this consumer).
 2. Repl integration (raw mode): trigger scheme preserving literal tab - candidates to
    evaluate at implementation time (decision recorded here): double-Tab, a dedicated
@@ -86,7 +88,7 @@ arginfo principle: introspection must not run commands to elicit usage).
   src/tests/modules/punk/ns/testsuites/ns/cmdflow.test (2026-07-08), including ensemble
   -parameters handling; the choice semantics by
   src/tests/modules/punk/args/testsuites/args/choices.test; forms by forms.test.
-- Archived-goal references in this file: G-001 achieved 2026-07-11 (goals/archive/G-001-pluggable-console-backends.md); G-040 achieved 2026-07-08 (goals/archive/G-040-punkargs-choicealiases.md).
+- Archived-goal references in this file: G-001 achieved 2026-07-11 (goals/archive/G-001-pluggable-console-backends.md); G-040 achieved 2026-07-08 (goals/archive/G-040-punkargs-choicealiases.md); G-041 achieved 2026-07-13 (goals/archive/G-041-punkargs-form-matching.md).
 
 ## Repl behaviour preserve-list + testability findings (2026-07-11, user-directed - pre-refactor ordering)
 

goals/G-055-tclcore-regen-workflow.md

@@ -134,4 +134,4 @@ other commands including the multi-form ::after.
   separate/block are the in-tree precedents). This extends the existing
   synopsis-translation exception: form structure, like synopsis notation, follows
   punkshell's modelling needs rather than the source document's presentation.
-- Archived-goal references in this file: G-049 achieved 2026-07-10 (goals/archive/G-049-punkargs-parse-status-model.md);G-054 achieved 2026-07-11 (goals/archive/G-054-tclcore-stringis-harvest.md).
+- Archived-goal references in this file: G-049 achieved 2026-07-10 (goals/archive/G-049-punkargs-parse-status-model.md);G-054 achieved 2026-07-11 (goals/archive/G-054-tclcore-stringis-harvest.md); G-041 achieved 2026-07-13 (goals/archive/G-041-punkargs-form-matching.md).

goals/G-072-punkargs-compound-clause-types.md

@@ -65,3 +65,4 @@ mechanism. Brief examination at drafting time:
 - Display cost matters: the ::try notes warn bracketed alternate forms "get
   unwieldy in synopsis listings" - synopsis rendering of compound types is part
   of the mechanism's acceptance, not an afterthought.
+- Archived-goal references in this file: G-041 achieved 2026-07-13 (goals/archive/G-041-punkargs-form-matching.md).