From ba2f77ed8a93ad96037349398dea77d0ebf134aa Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Sat, 1 Aug 2026 13:00:17 +1000 Subject: [PATCH] Goals: draft G-143/G-144/G-145 (user-approved proposals) G-143 make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage - @form sections with literal action leaders so help shows which actions take /-test, 'help ' renders the single form, tool dispatch becomes fully declared, buildsuite keeps its passthrough driver-args contract. G-144 punk::args auto-synopsis @cmd -name fallback for non-command ids - unblocks dropping make.tcl's hand-written ?...? @form -synopsis lines in favour of the automatic bracket notation (retires the G-030 workaround for (script):: ids). G-145 remnant-free piped usage tables - root-cause and eliminate the orphan CSI fragments ([0;1m / [0m / lone m) observed beside table borders in piped help output; extends the G-113 zero-ESC guarantee to zero sequence-fragment text. All three born from the 2026-08-01 argdoc restyle evaluation (mechanisms verified live on bootsupport punk::args 0.12.7). Overlap surveys recorded in each detail file; goals_lint clean (83 active-index goals); xref score reviewed per goal - the top term-scored unlinked pairs for G-143 (G-085, G-021) checked and judged lexical-only, no relation recorded. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- GOALS.md | 12 +++++++++ goals/G-143-maketcl-multiform-help.md | 25 +++++++++++++++++++ .../G-144-punkargs-synopsis-name-fallback.md | 24 ++++++++++++++++++ goals/G-145-piped-usage-ansi-remnants.md | 22 ++++++++++++++++ 4 files changed, 83 insertions(+) create mode 100644 goals/G-143-maketcl-multiform-help.md create mode 100644 goals/G-144-punkargs-synopsis-name-fallback.md create mode 100644 goals/G-145-piped-usage-ansi-remnants.md diff --git a/GOALS.md b/GOALS.md index cf48bd72..e601cb92 100644 --- a/GOALS.md +++ b/GOALS.md @@ -398,3 +398,15 @@ Detail: goals/G-141-libfetch-target-selection.md Scope: punkbin artifact repo (external c:/repo/jn/punkbin - layout contract, src/build_sha1sums.tcl, per-tier listing manifests); src/scriptapps/bin/ (punk-runtime payloads); bin/punk-runtime.cmd (regenerated output) + bin/AGENTS.md; src/tests/shell/testsuites/binscripts/; src/make.tcl (libfetch coordination) Detail: goals/G-142-punkbin-listing-manifests.md +### G-143 [proposed] make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage +Scope: src/make.tcl (::punkboot::argdoc definitions + help dispatch); src/tests/shell/testsuites/punkexe/ (new piped help characterization test) +Detail: goals/G-143-maketcl-multiform-help.md + +### G-144 [proposed] punk::args auto-synopsis: @cmd -name fallback for non-command ids +Scope: src/modules/punk/args-999999.0a1.0.tm (synopsis renderer + usage/arg_error synopsis display); src/tests/modules/punk/args/testsuites/args/ (synopsis pins) +Detail: goals/G-144-punkargs-synopsis-name-fallback.md + +### G-145 [proposed] Remnant-free piped usage tables: root-cause split ANSI fragments +Scope: src/make.tcl (::punkboot::ansistrip transform); src/modules/textblock-999999.0a1.0.tm + src/modules/punk/ansi-999999.0a1.0.tm (ANSI-aware cell/width handling as implicated); src/tests/shell/testsuites/punkexe/maketclcolour.test (remnant pin) +Detail: goals/G-145-piped-usage-ansi-remnants.md + diff --git a/goals/G-143-maketcl-multiform-help.md b/goals/G-143-maketcl-multiform-help.md new file mode 100644 index 00000000..8fa17b20 --- /dev/null +++ b/goals/G-143-maketcl-multiform-help.md @@ -0,0 +1,25 @@ +# G-143 make.tcl help depth: multi-form tool/buildsuite definitions and per-action usage + +Status: proposed +Scope: src/make.tcl (::punkboot::argdoc definitions + help dispatch); src/tests/shell/testsuites/punkexe/ (new piped help characterization test) +Goal: The tool and buildsuite subcommands are declared as multi-form punk::args definitions (one @form per action with a literal action leader and per-form opts/values) so that full-subcommand help renders one synopsis line per action - making it explicit which actions accept and -test where today's single line conflates them - 'make.tcl help ' renders that action's single-form usage, tool dispatch parses through the definition (pointed punk::args usage errors for unknown actions and flags), and buildsuite keeps its passthrough driver-args contract (forms serve its help/synopsis accuracy only). +Acceptance: 'make.tcl help tool' shows per-action synopsis lines (list; info; build with -test and toolnames; test with toolnames) instead of the single conflated line; 'make.tcl help tool build' and 'make.tcl help buildsuite build' render that form's usage table and an unknown action subject produces a punk::args usage error (exit 1); all currently-working tool invocations behave unchanged while 'make.tcl tool ' and unknown flags produce punk::args usage errors (exit 1); buildsuite driver-arg forwarding is unchanged (an arbitrary flag after 'buildsuite build ' still reaches the driver untouched); PUNKBOOT_PLAIN=1 degraded dispatch still handles the same invocations via the plain scan; the behaviours are pinned by a piped characterization test under src/tests/shell/testsuites/punkexe/. + +## Context + +G-030 (achieved 2026-07-14 - goals/archive/G-030-maketcl-punkargs.md) made make.tcl the punk::args showcase, but its tool/buildsuite definitions document the action surface as one line ('make.tcl tool list|info|build|test ? ...? ?-test 0|1?') that cannot say which optionals belong to which action, and 'make.tcl help tool list' is not supported - identified as underspecification of the showcase intent (user review 2026-08-01). The punk shell's 'i' (punk::ns::cmdhelp) renders per-form usage for exactly this shape; make.tcl should showcase the same depth. + +## Approach + +- Mechanisms verified live on bootsupport punk::args 0.12.7 (2026-08-01): @form sections with 'action -type literal()' leaders render per-action synopses; punk::args::usage -form renders a single-form table (@cmd -name in the COMMAND header); punk::args::parse auto-selects the form from the literal action word (result dict carries form/formstatus). In-tree exemplar: punk::auto_exec::hash (multi-form definition + handler form dispatch). +- help dispatch: the help subject gains an optional trailing action word mapped to usage -form; ' -help' can route the same way. +- tool becomes fully declared (its argument surface is a closed set); buildsuite build's trailing driver args stay a -type any -multiple passthrough (arbitrary driver flags must not be parsed as options). +- Definitions follow the braced -&/tstr argdoc house style (G-045 mechanisms - see src/modules/AGENTS.md "punk::args definition authoring ergonomics"). +- Same degrade contract as the existing argdoc block (guarded defines + get_spec probes; the plain fallback keeps today's passthrough behaviour). + +## Notes + +- Related: G-144 (sibling proposal) - auto-synopsis @cmd -name fallback; until it ships, per-form synopsis lines are hand-written (@form -synopsis, bracket notation preferred) or would display definition ids. +- Related: G-025 (proposed) - the future version-report subcommand should be born to these conventions (carried from G-030's notes). +- Overlap survey 2026-08-01: goals_xref paths src/make.tcl scores no intersects (make.tcl is a df-damped ubiquitous anchor); manual index sweep - the live make.tcl-scoped goals (G-005 G-006 G-012 G-019 G-023 G-026 G-027 G-028 G-029 G-063 G-065 G-067) are build/vendor mechanics with no help/dispatch overlap; punkexe-test-scoped goals (G-077 G-131 G-141) unrelated. +- Archived-goal references in this file: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md); G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md); G-104 achieved 2026-07-25 (goals/archive/G-104-maketcl-buildsuite-surface.md) - buildsuite surface whose passthrough contract this preserves; G-126 achieved 2026-07-27 (goals/archive/G-126-punkzip-accelerator.md) - origin of the tool subcommand. diff --git a/goals/G-144-punkargs-synopsis-name-fallback.md b/goals/G-144-punkargs-synopsis-name-fallback.md new file mode 100644 index 00000000..014f6ccd --- /dev/null +++ b/goals/G-144-punkargs-synopsis-name-fallback.md @@ -0,0 +1,24 @@ +# G-144 punk::args auto-synopsis: @cmd -name fallback for non-command ids + +Status: proposed +Scope: src/modules/punk/args-999999.0a1.0.tm (synopsis renderer + usage/arg_error synopsis display); src/tests/modules/punk/args/testsuites/args/ (synopsis pins) +Goal: Auto-generated synopses render their invocation name from @cmd -name whenever the definition id is not the command's invocation name (script-level ids like (script)::punkboot::modules and (shared)/(package)-style doc ids), falling back to the id only when no @cmd -name is declared - so consumers get the automatic bracket-notation synopsis with the real command name, and explicit @form -synopsis overrides become optional rather than mandatory for such ids. +Acceptance: a definition with @id -id (script)::x::sub and @cmd -name 'make.tcl sub' auto-renders synopsis lines beginning 'make.tcl sub' across the punk::args::synopsis, usage and arg_error surfaces (table and string renderers), with every form line of a multi-form definition carrying the name; definitions whose id equals the invocation name render byte-identical to today (existing synopsis/usage/arg_error suites pass unchanged apart from deliberately updated pins); a definition with neither a command-path id nor @cmd -name renders the id as today; the new behaviour is pinned in the args testsuite. + +## Context + +The synopsis generator produces the preferred bracket-notation lines but names the definition id verbatim: verified 2026-08-01 on punk::args 0.12.7 - '(script)::toy::flat [-test ] [toolname]...'. For script-level definitions (make.tcl's (script)::punkboot::) and shared/package doc ids, that forced the explicit @form -synopsis workaround adopted in G-030 and documented in G-045's authoring ergonomics; make.tcl hand-writes Tcl-style ?...? synopses for this reason alone, while the user-preferred style is the automatic punk::args bracket notation. + +## Approach + +- Display-only change: parsing, ids, get_spec and spec caching are untouched. +- Rule to settle in the work: when to prefer @cmd -name over id (candidates: ids carrying a parenthesised origin prefix like (script)/(shared)/(autodef), or any id differing from -name beyond a leading ::). Hard constraint: existing real-command definitions (id == command path) must render unchanged. +- Consumer follow-through: make.tcl drops its per-definition @form -synopsis lines once this ships (under G-143 if active, else a small follow-on edit). + +## Notes + +- Origin: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) recorded the id-vs-name synopsis finding and mooted this exact nicety; G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md) documents the explicit @form -synopsis lesson this retires for constructed/script ids. +- Related: G-050 (proposed) - synopsis validity marking; same renderer surface, independent mechanism. +- Related: G-056 (proposed) - display-time help wrapping; same renderer file, independent mechanism. +- Related: G-143 (sibling proposal) - make.tcl consumer of the fallback (auto bracket-notation synopses). +- Overlap survey 2026-08-01: goals_xref paths src/modules/punk/args-999999.0a1.0.tm lists the punkargs family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088); besides G-050/G-056 named above, these target parser/spec mechanisms, not synopsis name display. diff --git a/goals/G-145-piped-usage-ansi-remnants.md b/goals/G-145-piped-usage-ansi-remnants.md new file mode 100644 index 00000000..d0e8e54b --- /dev/null +++ b/goals/G-145-piped-usage-ansi-remnants.md @@ -0,0 +1,22 @@ +# G-145 Remnant-free piped usage tables: root-cause split ANSI fragments + +Status: proposed +Scope: src/make.tcl (::punkboot::ansistrip transform); src/modules/textblock-999999.0a1.0.tm + src/modules/punk/ansi-999999.0a1.0.tm (ANSI-aware cell/width handling as implicated); src/tests/shell/testsuites/punkexe/maketclcolour.test (remnant pin) +Goal: Piped make.tcl usage/help output is free of ANSI remnant text: the orphan CSI fragments observed in piped help tables ('[0;1m', '[0m', lone 'm' beside cell borders) are root-caused (renderer-side sequence splitting vs a strip-transform edge case) and eliminated at the producing layer, extending the G-113 zero-ESC guarantee to zero orphan sequence-fragment text while leaving interactive colour output unchanged. +Acceptance: piped 'tclsh src/make.tcl help ' for every declared subject plus bare 'make.tcl -help' yields output with no ESC bytes and no CSI-remnant substrings (regex {\[[0-9;:]*m}; the help corpus carries no such literal text), pinned in maketclcolour.test; the root cause and chosen fix layer are recorded in this file; existing colour-policy pins (tty/forced/nocolor modes) pass unchanged. + +## Context + +Observed 2026-08-01 while diffing before/after help captures for the argdoc restyle: piped help output intermittently carries ESC-less ANSI tails inside rendered tables (before the restyle: _toplevel x2, help, modules, vendorupdate; after: _toplevel x4, bakelist, bootsupport, help, info, libs - positions shift with table geometry, so the restyle did not introduce the class). Examples: '[0;1m' at a line end before a cell border, '[0m' at a row start, a lone 'm' beside a border. + +## Approach + +- Evidence so far: the G-113 write-side strip (::punkboot::ansistrip) already carries a trailing incomplete sequence across write chunks (per-channel carry; flush preserves it, finalize drops it), so a clean ESC-boundary split at the channel would be handled. First suspect is therefore upstream: styled content split by ANSI-aware width/cell handling before write, leaving ESC-less fragment text a byte-level strip correctly ignores. +- Piped runs do legitimately receive ANSI from module emitters (the strip is load-bearing by design - G-113); punk::args resolve caching also carries a colour-state staleness todo (cached specs can embed colour from resolve time), a possible fragment source to check. +- Diagnosis route: capture the pre-transform stream for an affected subject (transform popped, or PUNK_FORCE_COLOR run) and determine whether fragments exist pre-strip; fix in textblock/punk::ansi width handling if so, else harden the transform. + +## Notes + +- G-113 achieved 2026-07-25 (goals/archive/G-113-maketcl-tty-aware-colour.md) - the colour policy and zero-ESC pin surface (maketclcolour.test) this extends. +- Related: G-056 (proposed) - ANSI-aware wrap/width machinery ('styling in effect carries across the wrap'); if the root cause is renderer-side splitting, the fix layer coincides. +- Overlap survey 2026-08-01: goals_xref paths punk/ansi module -> G-078/G-079/G-080 (HTML rendering family, unrelated); textblock -> G-048 (table option parse), G-056 (named above), G-088 (footer rendering) - only G-056 shares the mechanism; punkexe tests -> G-077/G-131/G-141 (unrelated).