Browse Source
- G-049 flipped to achieved 2026-07-10 (acceptance verified on Tcl 9.0.3 + 8.7); detail file records the shipped design, the incomplete-vs-invalid classification judgement call, and verification results - G-054 [proposed]: ::tcl::string::is class choices harvested from the running interpreter at define time + cross-version behavioural parity pins (probing showed the static 9.0 list wrongly accepts dict on 8.6 - the real Tcl 8 target - and the hand model is otherwise behaviourally accurate incl the last-word-is-str C semantics) - G-055 [proposed]: agent-driven tclcore moduledoc regeneration workflow - Tcl source tree + version as input (TEMP_REFERENCE/tcl9 interim; retrieval deferred to buildsuites toml/G-005 era), verbatim text policy with two exceptions (synopsis notation translated to punkshell syntax; line re-folding while punk::args lacks word wrapping), real-vs-model parity probe as the verification gate, provenance recording, modelability gap scan; proving set = whole ::string ensemble + selected others incl multi-form ::after; tkcore (shared-section reuse a la tk_standardoptions) and core.tcl-lang.org projects (tcludp) to follow later - G-056 [proposed]: display-time word wrapping for punk::args help content (split-only never-join, ANSI/grapheme/double-width aware, paramindent-aligned continuations) - retires the G-055 folding exception for new work when shipped Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.commaster
4 changed files with 200 additions and 2 deletions
@ -0,0 +1,91 @@
|
||||
# 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. |
||||
@ -0,0 +1,57 @@
|
||||
# G-056 punk::args display-time word wrapping for help content |
||||
|
||||
Status: proposed |
||||
Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error table and string renderers, helpers), src/modules/textblock-999999.0a1.0.tm (only if cell/column-level wrap is the chosen mechanism), src/tests/modules/punk/args/testsuites/args/ (new wrapping characterization + existing rendering suites) |
||||
Acceptance: see GOALS.md index entry (canonical). |
||||
|
||||
## Context |
||||
|
||||
punk::args help rendering has no word wrapping: -help and choicelabel text renders |
||||
exactly as authored, so authors hand-fold lines short to stay terminal-friendly |
||||
(the convention throughout the codebase and the module documentation templates). |
||||
That convention forced a fidelity exception in the G-055 tclcore moduledoc |
||||
regeneration workflow: imported man-page prose must be manually re-folded rather |
||||
than stored verbatim. Renderer-side wrapping removes the need - definitions can |
||||
store unfolded verbatim text and the display adapts to the terminal. |
||||
|
||||
## Approach |
||||
|
||||
Core semantics: **split-only, never-join**. The renderer wraps logical lines that |
||||
exceed the effective width but never reflows or joins existing line breaks. This |
||||
preserves deliberately structured content (hand-folded paragraphs, embedded choice |
||||
tables, textblock-frame art choicelabels, indented continuation blocks) by |
||||
construction, with no per-field opt-in/opt-out annotation machinery - and makes |
||||
"existing content renders byte-identical" a directly testable invariant. |
||||
|
||||
Width handling to the same standard as the rest of the punk display stack: |
||||
ANSI-aware (SGR sequences measure zero width; styling in effect at a wrap point |
||||
carries onto the continuation), grapheme-cluster and double-width aware |
||||
(punk::ansi / punk::char facilities). Wrapped continuations indent to the field's |
||||
existing alignment (the paramindent machinery from G-046 governs where |
||||
continuation lines sit today - wrapping must land continuations at the same |
||||
column, not at column 0). |
||||
|
||||
Effective width: terminal width when detectable (punk::console), falling back to |
||||
the current table -maxwidth 80 default; an explicit width option overrides both. |
||||
|
||||
### Mechanism alternatives (decide during the work, record here) |
||||
|
||||
- **punk::args-side pre-wrap**: wrap field text in the arg_error/usage renderers |
||||
before handing cells to textblock::table (and before the -return string |
||||
renderer's line assembly). Smaller blast radius; wrap width must anticipate the |
||||
table's computed column widths - a chicken-and-egg with column autosizing that |
||||
may need a measure pass or fixed help-column budget. |
||||
- **textblock table column wrap**: a -wrap/-maxwidth-aware column feature in |
||||
textblock::class::table cells. More general (benefits every table consumer), |
||||
heavier; interacts with existing cell padding/ansibase handling and the table's |
||||
width negotiation. If chosen, textblock's buildversion and tests are in scope. |
||||
|
||||
## Notes |
||||
|
||||
- Cross-link: [[G-055]] - its "re-folding to display width" exception to verbatim |
||||
text lapses for new work once this ships (mark it there on achievement). |
||||
- The -return string renderer has its own continuation-alignment conventions |
||||
(Description-label alignment added in G-046); wrapped continuations must respect |
||||
those, not just the table path. |
||||
- Characterization first: pin current no-wrap rendering of an over-width line |
||||
(overflow behaviour) before changing it, per the usual GAP-pin workflow. |
||||
Loading…
Reference in new issue