From 7e7d515cd0e19c09f6ea1a6c6bd3abed06b5a517 Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Mon, 13 Jul 2026 02:19:07 +1000 Subject: [PATCH] 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 ' 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 | 3 ++ GOALS.md | 4 --- goals/G-041-punkargs-form-matching.md | 35 ++++++++++++++++++- goals/G-044-repl-command-completion.md | 10 +++--- goals/G-055-tclcore-regen-workflow.md | 2 +- goals/G-072-punkargs-compound-clause-types.md | 1 + 6 files changed, 45 insertions(+), 10 deletions(-) diff --git a/GOALS-archive.md b/GOALS-archive.md index cb446fc7..9b1af36d 100644 --- a/GOALS-archive.md +++ b/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. diff --git a/GOALS.md b/GOALS.md index 5083b80e..106c0a4f 100644 --- a/GOALS.md +++ b/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 diff --git a/goals/G-041-punkargs-form-matching.md b/goals/G-041-punkargs-form-matching.md index b583fc75..2582d91c 100644 --- a/goals/G-041-punkargs-form-matching.md +++ b/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 ' 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 ' and synopsis output indicate the best-matching form(s) for supplied args; explicit -form 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 ' 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 diff --git a/goals/G-044-repl-command-completion.md b/goals/G-044-repl-command-completion.md index a29707b1..39d053e0 100644 --- a/goals/G-044-repl-command-completion.md +++ b/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) - and show all/form-0 synopses with the limitation noted; when G-041's candidacy API - exists, rank/filter forms by the partial input (G-041's detail file notes the API + Form handling: G-041 (achieved 2026-07-13) shipped the candidacy API this consumes + - punk::args::parse_status reports per-form compatibility for a (partial) argument + 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) diff --git a/goals/G-055-tclcore-regen-workflow.md b/goals/G-055-tclcore-regen-workflow.md index 93d77815..027a042d 100644 --- a/goals/G-055-tclcore-regen-workflow.md +++ b/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). diff --git a/goals/G-072-punkargs-compound-clause-types.md b/goals/G-072-punkargs-compound-clause-types.md index 99fca05d..4b1bafda 100644 --- a/goals/G-072-punkargs-compound-clause-types.md +++ b/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).