punkshell

1318 Commits

1 Branch

1 Tag

221 MiB

Commit Graph

Author	SHA1	Message	Date
Julian Noble	15a7e27acb	G-145 achieved: ansistrip transform drops 'clear' op - remnant-free piped help The Tcl core delivers 'clear' to a transform stack before EVERY write op (output-buffer flush-down; tclIORTrans.c ReflectOutput, gated on METH_CLEAR - intentional and test-pinned, but under-documented: doc/transchan.n and TIP 230 scope clear to seek/read-side buffers). ::punkboot::ansistrip::transchan's clear handler ran 'dict unset carry $chanid', discarding a split sequence's held ESC tail at every write-chunk boundary: the next chunk's ESC-less remainder ('0;1m', '1m') passed through unstripped as orphan fragment text in piped usage tables, while the dropped ESC bytes kept the G-113 zero-ESC pin green. The transform is write-only with no read-side state, so its contract-conformant clear is a no-op - it no longer declares the op, the per-write calls never fire, and the split-sequence carry survives every chunk boundary. finalize still drops an end-of-stream partial sequence. No change in textblock/punk::ansi (pre-transform stream verified well-formed during diagnosis; exonerated). Pin: maketclcolour.test gains maketcl_colour_help_tables_zero_remnants - piped 'tclsh src/make.tcl help' for all 20 declared SUMMARIES subjects plus bare 'help'/'-help', asserting exit 0, zero ESC bytes, zero orphan fragments (two-step detector: strip complete sequences, then scan for [0-9;]+m not preceded by ESC or an open bracket - a raw scan false-positives on ';1m' inside complete multi-parameter SGR). Failing-first evidence: pre-fix the pin names exactly the 5 fragmenting invocations (help, -help, help libs, help info, help bootsupport); the 22-invocation NO_COLOR+PUNK_FORCE_COLOR pre-transform corpus carries no legit text matching the detector. Verified (tclsh 8.7a6, win32-x86_64): all 22 invocations byte-level clean; PUNK_FORCE_COLOR=1 output intact (1177 complete sequences, 0 orphans); the 3 G-113 colour-policy pins pass unchanged; shell/testsuites/punkexe family (15 files, 102 tests) and shell/*** (127 tests) green, warnings pre-existing only; 'make.tcl packages' verified, layout + modpod make.tcl copies synced by the build (punkcheck-managed outputs batched here per the carve-out). Bookkeeping: goal flipped active -> achieved 2026-08-01, detail file archived (goals/archive/G-145-piped-usage-ansi-remnants.md), G-056 Notes gains the exoneration pointer; src/AGENTS.md colour bullet + src/tests/shell/AGENTS.md suite description updated; project version 0.39.4 (patch) with CHANGELOG entry. Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown	1 week ago
Julian Noble	c7229739c3	G-145 root cause: ansistrip 'clear' op drops the split-sequence carry (record + shellfilter warning) Investigation record only - no fix yet (goal remains proposed). Root cause: the Tcl core delivers the transform 'clear' op before every write (output-buffer flush-down; tclsh 8.7 and 9.0.3), and ::punkboot::ansistrip's transchan handles 'clear' with 'dict unset carry' - discarding a split sequence's held tail at every chunk boundary. The tail's remainder (e.g. 0;1m) passes through unstripped while the held ESC[ bytes are never emitted, so the zero-ESC pin (maketclcolour.test) stays green while fragments leak. Evidence: pre-transform stream captured via NO_COLOR+PUNK_FORCE_COLOR is fully well-formed (textblock/punk::ansi exonerated; G-056 not the mechanism); the verbatim strip proc is correct for every possible 2-chunk split and 512..8192 block sizes; an identity logging transform under ansistrip captured the boundary byte-exactly; minimal isolated repro on a bare file channel reproduces both the per-write 'clear' op sequence and a fragment. Deterministic per table geometry, matching the observed intermittency. Upstream (TEMP_REFERENCE/tcl9 survey): per-write 'clear' is intentional, test-pinned core behavior (ioTrans.test iortrans-7.1 "chan write, write clears read buffers") but transchan.n and TIP 230 document it as seek-only and read-side-scoped - an upstream documentation gap, not an implementation bug; no existing Tcl ticket found. A write-only transform's contract-conformant 'clear' is a no-op; fix layer recorded in the goal file (drop 'clear' from the supported-methods list or make it a no-op; 'finalize' keeps dropping the carry). - goals/G-145-piped-usage-ansi-remnants.md: root cause, evidence chain, upstream documentation status, fix layer, encoding note, repro recipes - shellfilter: G-145 warning comment over the commented-out 'clear' method so future refactors don't discard o_encbuf/stream state there goals_lint clean (83 active-index goals, 62 archived). Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown	1 week ago
Julian Noble	ba2f77ed8a	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 <toolname>/-test, 'help <sub> <action>' 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	1 week ago

Author

SHA1

Message

Date

Julian Noble

15a7e27acb

G-145 achieved: ansistrip transform drops 'clear' op - remnant-free piped help

The Tcl core delivers 'clear' to a transform stack before EVERY write op
(output-buffer flush-down; tclIORTrans.c ReflectOutput, gated on METH_CLEAR -
intentional and test-pinned, but under-documented: doc/transchan.n and TIP 230
scope clear to seek/read-side buffers). ::punkboot::ansistrip::transchan's
clear handler ran 'dict unset carry $chanid', discarding a split sequence's
held ESC tail at every write-chunk boundary: the next chunk's ESC-less
remainder ('0;1m', '1m') passed through unstripped as orphan fragment text in
piped usage tables, while the dropped ESC bytes kept the G-113 zero-ESC pin
green. The transform is write-only with no read-side state, so its
contract-conformant clear is a no-op - it no longer declares the op, the
per-write calls never fire, and the split-sequence carry survives every chunk
boundary. finalize still drops an end-of-stream partial sequence. No change in
textblock/punk::ansi (pre-transform stream verified well-formed during
diagnosis; exonerated).

Pin: maketclcolour.test gains maketcl_colour_help_tables_zero_remnants -
piped 'tclsh src/make.tcl help' for all 20 declared SUMMARIES subjects plus
bare 'help'/'-help', asserting exit 0, zero ESC bytes, zero orphan fragments
(two-step detector: strip complete sequences, then scan for [0-9;]+m not
preceded by ESC or an open bracket - a raw scan false-positives on ';1m' inside complete
multi-parameter SGR). Failing-first evidence: pre-fix the pin names exactly
the 5 fragmenting invocations (help, -help, help libs, help info, help
bootsupport); the 22-invocation NO_COLOR+PUNK_FORCE_COLOR pre-transform
corpus carries no legit text matching the detector.

Verified (tclsh 8.7a6, win32-x86_64): all 22 invocations byte-level clean;
PUNK_FORCE_COLOR=1 output intact (1177 complete sequences, 0 orphans); the 3
G-113 colour-policy pins pass unchanged; shell/testsuites/punkexe family (15
files, 102 tests) and shell/*** (127 tests) green, warnings pre-existing only;
'make.tcl packages' verified, layout + modpod make.tcl copies synced by the
build (punkcheck-managed outputs batched here per the carve-out).

Bookkeeping: goal flipped active -> achieved 2026-08-01, detail file archived
(goals/archive/G-145-piped-usage-ansi-remnants.md), G-056 Notes gains the
exoneration pointer; src/AGENTS.md colour bullet + src/tests/shell/AGENTS.md
suite description updated; project version 0.39.4 (patch) with CHANGELOG
entry.

Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown

1 week ago

Julian Noble

c7229739c3

G-145 root cause: ansistrip 'clear' op drops the split-sequence carry (record + shellfilter warning)

Investigation record only - no fix yet (goal remains proposed).

Root cause: the Tcl core delivers the transform 'clear' op before every
write (output-buffer flush-down; tclsh 8.7 and 9.0.3), and
::punkboot::ansistrip's transchan handles 'clear' with 'dict unset carry'
- discarding a split sequence's held tail at every chunk boundary. The
tail's remainder (e.g. 0;1m) passes through unstripped while the held
ESC[ bytes are never emitted, so the zero-ESC pin (maketclcolour.test)
stays green while fragments leak. Evidence: pre-transform stream captured
via NO_COLOR+PUNK_FORCE_COLOR is fully well-formed (textblock/punk::ansi
exonerated; G-056 not the mechanism); the verbatim strip proc is correct
for every possible 2-chunk split and 512..8192 block sizes; an identity
logging transform under ansistrip captured the boundary byte-exactly;
minimal isolated repro on a bare file channel reproduces both the
per-write 'clear' op sequence and a fragment. Deterministic per table
geometry, matching the observed intermittency.

Upstream (TEMP_REFERENCE/tcl9 survey): per-write 'clear' is intentional,
test-pinned core behavior (ioTrans.test iortrans-7.1 "chan write, write
clears read buffers") but transchan.n and TIP 230 document it as
seek-only and read-side-scoped - an upstream documentation gap, not an
implementation bug; no existing Tcl ticket found. A write-only
transform's contract-conformant 'clear' is a no-op; fix layer recorded
in the goal file (drop 'clear' from the supported-methods list or make
it a no-op; 'finalize' keeps dropping the carry).

- goals/G-145-piped-usage-ansi-remnants.md: root cause, evidence chain,
  upstream documentation status, fix layer, encoding note, repro recipes
- shellfilter: G-145 warning comment over the commented-out 'clear'
  method so future refactors don't discard o_encbuf/stream state there

goals_lint clean (83 active-index goals, 62 archived).

Assisted-by: harness=opencode; primary-model=opencode/kimi-k3; api-location=unknown

1 week ago

Julian Noble

ba2f77ed8a

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 <toolname>/-test, 'help <sub> <action>' 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

1 week ago

1 Commits (120ca92b496d27d33158f743333091ded4ee51de)