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

G-055 Agent-driven tclcore moduledoc regeneration workflow with behavioural parity verification

Status: proposed Scope: goals/G-055-tclcore-regen-workflow.md (workflow doc), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (+ buildversion), src/tests/modules/punk/args/testsuites/args/ (parity pins), TEMP_REFERENCE/tcl9 (read-only source input; source retrieval mechanism deferred to the buildsuites toml configs / G-005 era) Acceptance: see GOALS.md index entry (canonical).

Context

punk::args::moduledoc::tclcore was produced manually from the Tcl man pages. A behavioural audit of 'string is' (2026-07-10, driven by the G-049 parse_status machinery) showed the hand modelling to be surprisingly accurate - arity, the "last word is always str" C-parser semantics, option/class prefix acceptance and ambiguity rejection all agree with the real interpreter - but exposed the failure mode manual transcription cannot avoid: version drift in enumerated facts. The static class list is the Tcl 9.0 set, so 'string is dict' is wrongly accepted when running under 8.6 (dict is 8.7+/9.x). Note 8.6, not 8.7, is the real Tcl 8 target: 8.7 is unreleased and unmaintained (its 'unicode' class never shipped in any released Tcl; 9.0 removed it).

The audit method generalizes and is the maintainability answer: doc authoring needs judgement (the man pages are not consistently machine-parsable; some text belongs in @examples, some in choicelabels - rearrangement yes, reimagining no), but doc verification is mechanical - drive the same argument shapes through the real command (safe, deliberately-invalid invocations) and through punk::args::parse_status against the definition, and require error-vs-ok agreement. G-054 applies this tactically to 'string is'; this goal makes it a repeatable workflow.

Approach

Workflow inputs: a Tcl source tree (doc/.n man pages, generic/.c for ground truth) plus its version/checkin id. For now the tree is TEMP_REFERENCE/tcl9 (reference-only fossil checkout); how source trees are fetched (git/fossil, to a settled location) is a buildsuites/G-005-era decision - the workflow only takes "path + version" and must stay indifferent to how the tree arrived.

Per command:

1. Read the man page section and, where behaviour is load-bearing (arity, option windows, enum tables), the C implementation.
2. Author/refresh the punk::args definition block - verbatim text, rearranged into @cmd -help/@examples/argument -help/choicelabels as fits the punk::args idiom. Exception to verbatim: synopsis notation. punkshell deliberately uses its own, more generic synopsis syntax (as rendered by punk::ns::synopsis / @form -synopsis), so synopsis lines and usage examples embedded in the source docs (man-page SYNOPSIS sections, wrong-#-args strings like "class ?-strict? ?-failindex var? str") are TRANSLATED into that syntax, never copied in Tcl's notation. Prose and semantic descriptions stay verbatim. Second exception: line folding. punk::args help rendering currently has no word wrapping, so source text is re-folded manually to keep help blocks terminal-width friendly (the existing convention of short hand-wrapped lines in -help/choicelabel blocks). Folding changes whitespace/line breaks only - words and their order stay verbatim. If punk::args later gains word wrapping, this exception lapses for new work. Enumerations the runtime can answer (class lists etc.) are harvested at define time rather than hard-coded (G-054 technique); released-version differences (8.6 vs 9.x) handled by version-conditional definition in the single adaptive package - no per-major package forks.
3. Verification gate: a probe matrix (valid, incomplete, invalid, prefix, flag-lookalike shapes) run against the real command and parse_status, asserting error-vs-ok agreement; committed as a parity test deriving expectations from the live interpreter, not version arithmetic.
4. Record provenance: the source checkin id the text was read from, noted with the definition (comment) and in the module changelog.

Modelability scan: an initial pass across tclcore commands to identify constructs the current punk::args system cannot model adequately (e.g exotic clause grammars, context-dependent option windows). Each gap is recorded here and flagged as a candidate goal - not silently approximated in doc blocks.

Proving set for acceptance: the whole ::string ensemble, plus a small selection of other commands including the multi-form ::after.

Notes

• tkcore: a started moduledoc loads on 'package require tk'. It is to be treated with the same workflow later, but relies heavily on shared documentation sections as currently modeled by the (default)::punk::args::moduledoc::tkcore::tk_standardoptions id - the workflow's text-placement guidance must cover shared-section reuse, so common option text is referenced once rather than duplicated per widget.
• Other core.tcl-lang.org projects (e.g core.tcl-lang.org/tcludp) get moduledocs following the same pattern further down the track; out of scope here beyond the workflow being reusable.
• The 'string is' audit artifacts (probe matrices and real-vs-model comparisons on 9.0.3 / 8.7a6 / 8.6.13) that motivated this goal are summarized in the G-049 session work of 2026-07-10; the C ground truth for the option-window semantics is StringIsCmd in generic/tclCmdMZ.c (objv[2..objc-2] option loop - the final word is unconditionally str).
• Probing policy: define-time/verification probing is limited to safe, side-effect-free invocations of pure builtins (deliberately-invalid calls harvesting error metadata). This does not relax cmdhelp's rule of never calling arbitrary commands to elicit usage at query time.