G-044 proposed: punk::args-driven repl command completion/hinting; cross-goal weaves

User-approved goal for interactive command completion and hinting in the repl
(raw mode primary), driven by the punk::args documentation corpus:

- command-word resolution via the same doc-lookup flow as 'i' (ensembles,
  subcommands, ensemble parameters - characterized in cmdflow.test), argument
  position via the definitions (options, choices with parse-consistent
  prefix/deny/reserve matching, literals, multi-form awareness per G-041)
- activation preserves the editbuf's literal-tab support (tab is content in
  this shell - completion cannot exclusively claim plain Tab; trigger scheme
  decided and recorded at implementation)
- per-subshell completion-provider seam: the punk::args completer is the
  default provider; a subshell can declare an alternative or none - minimum
  bar is a clean disable for language subshells such as an interactive xtal
  session (full xtal completion out of scope, not precluded)
- introspection must not execute candidate commands (arginfo principle);
  no per-keystroke terminal queries added when idle (G-013 approach note)

Detail-file weaves from the same direction:
- G-041: form candidacy should be exposed as an API accepting PARTIAL argument
  lists (per-form compatibility while typing) for the G-044 hinting consumer
- G-043: subshell definitions gain a repl-behaviour composition aspect
  (completion/syntax provider); xtal-style language subshells recorded as the
  motivating scenario, an actual xtal session deferred to its own future goal
- G-013: raw editor essentials noted as G-044's prerequisite; the editbuf
  literal-tab constraint recorded as a standing approach note

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

GOALS.md

@@ -308,3 +308,9 @@ Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler), src/m
 Detail: goals/G-043-subshell-definition-plugins.md
 Goal: a named subshell's definition - commandset imports (punk::overlay), help topics (the G-042 registry API) and config defaults - can be supplied by provider packages registered through a punk.subshell capability (punk::cap handler validating declarations) and/or declared in stored config (toml per G-014, naming already-installed commandset packages - absorbing punk::overlay's "toml configuration files for defining CLI configurations" todo), with punk::pluginmgr as the discovery/safe-interp trust layer for providers not already trusted - so entering a subshell composes its command surface and help from declarations instead of hardcoded init code.
 Acceptance: a provider package declaring the punk.subshell capability supplies at least a commandset binding (namespace + prefix) and a help-topic set for a named subshell, and entering that subshell composes them (prefixed commands callable, topics in 'help topics'/'i help') with quit/switch-away restoring the parent surface (no leakage); the punk.subshell punk::cap handler validates declarations (malformed declarations vetoed with a useful message); a subshell's commandset composition can equivalently be declared in stored config without a provider package (G-014 substrate), and the existing hardcoded 'dev' CLI composition keeps working unchanged; declarations for capabilities with no registered handler are discoverable (query or report - closing the silent punk.isbogus gap); punk::cap pkg_unregister leaves no stale handler state (the 'destroy api objects?' review resolved); punk::pluginmgr-based discovery/loading of a provider is either demonstrated end-to-end (including .tm module loading in the safe interp) or explicitly deferred with the remaining pluginmgr gaps recorded in the detail file; G-042's registry mechanism is consumed, not duplicated.
+
+### G-044 [proposed] punk::args-driven interactive command completion and hinting in the repl (raw mode primary)
+Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering)
+Detail: goals/G-044-repl-command-completion.md
+Goal: the interactive repl (raw mode primary) offers command completion and hinting driven by punk::args documentation - the command word resolved through the same doc-lookup flow as 'i' (ensembles, subcommands, ensemble parameters) and the argument position through the definition (options, choices with parse-consistent matching, literals, form awareness per G-041) - via an activation scheme that preserves the editbuf's literal-tab support (not exclusively plain Tab), behind a per-subshell completion-provider seam so alternative-language subshells (e.g. an interactive xtal session) can replace, augment or cleanly disable the Tcl-centric completer.
+Acceptance: in a raw-mode interactive session a documented trigger (recorded in the detail file; a literal tab remains enterable into the editbuf) presents completions for command words, ensemble subcommands (resolved via the punk::ns doc-lookup flow without executing candidate commands), option flags and choice values (matching consistent with parse semantics: prefix/deny/reserve, and aliases once G-040 lands); a hint display shows the synopsis of the form(s) matching the partial input (consumes G-041's candidacy API when available - until then all-forms or form-0 display with the limitation noted is acceptable); no per-keystroke terminal queries are added when no completion display is active (G-013 approach note); the completer is a provider interface with the punk::args-driven implementation as the default - a subshell can declare an alternative provider or none, proven at minimum by a subshell with completion disabled showing no Tcl-centric interference (the xtal minimum bar; full xtal completion out of scope but not precluded by the interface); line-mode behaviour is unchanged unless a documented subset is added; G-013's raw editor essentials are a prerequisite and this goal does not weaken G-013's acceptance.

goals/G-013-raw-mode-default.md

@@ -24,7 +24,9 @@ the line-mode type-ahead-loss window during terminal-query raw cycling
    running repl, default off.
 2. **Right-hand live editbuf view** (console_editbufview, repl ~2043, called ~2315) -
    currently ungated. An important development aid for per-keystroke features
-   (e.g. command completion) and stays available, but behind its own separate gate.
+   (e.g. command completion - now goal G-044, for which this goal's raw editor
+   essentials are the prerequisite) and stays available, but behind its own separate
+   gate.
    Its startup default should ultimately come from stored configuration via
    ::punk::config (see G-014) - toml-backed, independently configurable per named
    subshell - with off as the built-in fallback. Longer term, once the console
@@ -60,6 +62,9 @@ stays (see inventory item 4).
 - Raw editor stubs to replace: arrow-right/up and esc currently just rputs debug
   notices (repl ~2477-2492); history navigation and cursor movement are the
   parity items.
+- The editbuf supports literal tab entry (tab is content, not only a UI gesture) -
+  a standing constraint that G-044's completion-activation scheme must preserve
+  (completion triggering cannot exclusively claim plain Tab).
 - Toggle startup defaults resolve through ::punk::config stored configuration when
   available (G-014); built-in defaults apply when no configuration exists.
 

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

@@ -54,6 +54,13 @@ form-selection logic lands.
 5. Error-message quality: a no-form-matches error should show per-form failure reasons
    compactly rather than only form 0's.
 
+Downstream consumer note (2026-07-08, G-044): the interactive command-completion/hinting
+goal consumes form candidacy on PARTIAL argument lists - as the user types, the hinting
+display wants "which forms are still compatible with the words so far" - so the candidacy
+mechanism should be exposed as an API that accepts an incomplete argument list and returns
+per-form compatibility (not only an all-or-nothing full parse). Design for that consumer
+when shaping step 1.
+
 ## Alternatives considered
 
 - Documenting alternate forms as separate subhelp choiceinfo entries (the trace-style

goals/G-043-subshell-definition-plugins.md

@@ -110,3 +110,12 @@ Phases:
   a punk.subshell declaration's resources are resolved.
 - Related review record: goals/G-042-subshell-help-topics.md "Relationship to the
   intended plugin facility" section (same 2026-07-08 review).
+- Additional composition aspect (user direction 2026-07-08, recorded via G-044): a
+  subshell definition may also declare repl-behaviour aspects - at minimum a
+  command-completion provider (G-044's provider seam: replace, augment, or disable the
+  default punk::args-driven completer), potentially syntax-related behaviour later. The
+  motivating scenario is a language subshell such as an interactive xtal session
+  (https://tarray.magicsplat.com/xtal_lang.html - alternative syntax translated to Tcl):
+  such a subshell would compose an evaluator/commandset, its own help topics, and a
+  non-Tcl completion provider (or none). An actual xtal session is not owned by this
+  goal - when pursued it becomes its own goal built on this composition.

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

@@ -0,0 +1,87 @@
+# G-044 punk::args-driven interactive command completion and hinting in the repl (raw mode primary)
+
+Status: proposed
+Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering)
+Acceptance: in a raw-mode interactive session a documented trigger (recorded in the detail file; a literal tab remains enterable into the editbuf) presents completions for command words, ensemble subcommands (resolved via the punk::ns doc-lookup flow without executing candidate commands), option flags and choice values (matching consistent with parse semantics: prefix/deny/reserve, and aliases once G-040 lands); a hint display shows the synopsis of the form(s) matching the partial input (consumes G-041's candidacy API when available - until then all-forms or form-0 display with the limitation noted is acceptable); no per-keystroke terminal queries are added when no completion display is active (G-013 approach note); the completer is a provider interface with the punk::args-driven implementation as the default - a subshell can declare an alternative provider or none, proven at minimum by a subshell with completion disabled showing no Tcl-centric interference (the xtal minimum bar; full xtal completion out of scope but not precluded by the interface); line-mode behaviour is unchanged unless a documented subset is added; G-013's raw editor essentials are a prerequisite and this goal does not weaken G-013's acceptance.
+
+## Context
+
+User direction (2026-07-08): the raw mode repl system will use punk::args based
+documentation to retrieve enough information about incomplete commands - taking note of
+different forms - to provide interactive command-completion and hinting.
+
+Constraints stated up front:
+
+- The editbuf must continue to support literal tabs, so completion activation is not
+  purely Tab-based. (Tab is data in this shell, not only a UI gesture.)
+- The Tcl/punk::args-centric completer must be able to get out of the way: the
+  motivating non-Tcl scenario is an interactive session for an alternative syntax such
+  as the xtal Tcl package (https://tarray.magicsplat.com/xtal_lang.html) running as a
+  subshell, perhaps with plugin-defined repl behaviour for completion/syntax. The
+  minimum bar for this goal is a clean disable/replace seam; actual xtal completion or
+  an xtal session itself is not this goal's deliverable.
+
+Why punk::args is the right substrate: the definitions already carry per-position
+knowledge - leaders (including ensemble parameters), option names, choice sets with
+prefix/deny/reserve semantics (choices.test), literal/literalprefix types, and multiple
+forms - and the punk::ns doc-lookup flow (cmdwhich/cmdinfo/cmd_traverse, characterized in
+cmdflow.test 2026-07-08) already resolves command words through aliases, ensembles,
+subhelp choiceinfo and ensemble parameters WITHOUT executing candidate commands (the
+arginfo principle: introspection must not run commands to elicit usage).
+
+## Approach (sketch - to be refined when activated)
+
+1. Introspection layer (no repl dependency, testable headless):
+   given a partial word-list, return a completion/hint dataset - candidate next words
+   (subcommands from choiceinfo, option flags, choice values, literals from -type),
+   plus the synopsis/form information for the current position. Sources:
+   punk::ns::cmdinfo for the command-word path, punk::args::get_spec for the argument
+   position. Choice-word matching must reuse the parser's resolution rules (the shared
+   choice-resolution helper planned in G-040 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
+   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
+   chord (e.g. ctrl-space), Tab-completes-only-after-non-whitespace with an escape to
+   insert a literal tab, or fully configurable binding via G-014 config. Hinting may be
+   passive (status/ghost line) independent of the completion trigger. Rendering budget:
+   no added per-keystroke terminal queries when idle (G-013 approach note - cache
+   console size with invalidation); the G-013 editbuf live-view debug gate is the
+   development aid for this work (G-013 debug inventory item 2).
+3. Provider seam: the completion engine behind an interface (provider per subshell);
+   the punk::args-driven implementation is the default provider. A subshell declares an
+   alternative provider or none - the declaration rides the subshell-definition
+   composition of G-042/G-043 (a punk.subshell provider or stored-config entry may name
+   a completion provider alongside commandsets and help topics). Language subshells
+   (xtal-style: alternative syntax translated to Tcl) are the motivating consumer; an
+   actual interactive xtal session would be its own goal when pursued, composing a
+   G-043 subshell definition (commandset/evaluator, help topics, completion provider).
+
+## Alternatives considered
+
+- Command-name-only completion (readline-style over info commands) - insufficient: the
+  value is in argument-position awareness (subcommands, flags, choices, forms) which the
+  punk::args corpus already encodes.
+- Executing candidate commands to discover usage - rejected: the established arginfo
+  principle forbids running commands for introspection (risky side effects); everything
+  needed is available declaratively.
+- Hardcoding Tab as the only trigger - rejected per the literal-tab constraint; the
+  editbuf accepts tab characters as content.
+
+## Notes
+
+- Prerequisites/relations: G-013 (raw mode default + editor essentials - prerequisite;
+  its editbuf live view is the dev aid; its no-per-keystroke-query note is adopted),
+  G-041 (form candidacy on partial input - consumed when available), G-040 (choice
+  alias resolution shared with the parser), G-042/G-043 (per-subshell provider
+  declaration), G-014 (configurable trigger/bindings and per-subshell defaults).
+- xtal reference: https://tarray.magicsplat.com/xtal_lang.html - an alternative syntax
+  for Tcl (tarray project); an interactive xtal subshell is the concrete
+  language-subshell scenario the provider seam must not preclude.
+- The doc-lookup flow this consumes is characterized by
+  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.