New scriptlib/developer/nslist.tcl backing the new cross-framework tcl-nslist
agent skill (.agents/skills/ canonical, .claude/skills/ synced copy): the
discovery counterpart of whatis.tcl - lists what a namespace/package actually
exposes at runtime via punk::ns::get_ns_dicts (the n// machinery): child
namespaces with loadable-package markers, commands classified by kind,
punk::args-documented commands, -synopsis whole-namespace usage lines,
-pathcommands namespace-path resolution. Auto-package-requires unloaded
packages and follows ensemble commands to their implementation namespace.
The tcl-whatis skill/script cross-reference it (whatis redirects with a hint
when the queried name is a namespace, not a command).
punk::ns 0.9.1: get_ns_dicts packagetails/packageprefixes initialization moved
inside the per-namespace loop - with multiple matched namespaces (path globs,
trailing **) every dict after the first carried the union of all earlier
namespaces' entries, mis-marking non-package children in nslist/n// underline
styling and in the returned data; a child with several deeper packages below
it was appended to packageprefixes once per matching package (now once).
Pinned in nslist.test (nslist_classification_multins_package_buckets_reset).
Documentation-only PUNKARGS added for get_ns_dicts (returned dict keys
documented) and nslist_dict; parsing stays manual.
Root AGENTS.md: introspection note + scriptlib/developer inventory updated.
Project version 0.15.1 + CHANGELOG entry. punk::ns suite 102/102 pass.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The multiproc child bootstrap no longer preloads shellrun + the no-op
runx warmup: 17 test files gained their missing explicit package
require lines (punk::ansi for the bare ansi suites, punk::args for the
bare args suites incl dev/dynamic-cache, punk::lib for the lib suites
and for grepstr/untabify/examples whose punk::ansi/punk::args commands
reach punk::lib internally, plus textblock for examples.test - caught
by the empirical lean run: punk::args only soft-requires textblock and
punk::args::helpers::example calls textblock::join). Children now load
only tcltest plus each file's declared deps; the singleproc testinterp
keeps shellrun as the runner's own capture mechanism.
Module-web finding recorded in src/tests/AGENTS.md and the test-file
comments rather than fixed: punk::ansi and punk::args call punk::lib
without requiring it, and a hard back-require is blocked by punk::lib's
own hard require of punk::args (cycle) - deps declared at test level;
a considered module-level resolution remains open.
UDP watch-mode note folded into child_test_runner.tcl per user
direction: no interaction today (the parent relays child output at file
granularity; verified post-lean - events + relay flow); any future live
per-child tee must be conditional on PUNK_TEST_UDPTEE so unwatched
children stay lean.
Verified (native tclsh 9.0.3): full-suite PARITY ok for lean -jobs 16
vs the pre-lean baseline, between repeated lean -jobs 16 runs, and
lean -jobs 1 vs -jobs 16 (989/973/15/1, exec-14.3 sole failure).
Timings: -jobs 16 70.7s -> 49-53s; sequential multiproc ~5m30 -> 4m32;
singleproc unchanged. AGENTS scaling guidance refreshed.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User request after console-context failures went unnoticed: compact
per-file status words, failure/warning list entries, the per-file
had-failures/passed/child-failed notices, the markdown
failures/warnings file lists, the tally Passed/Failed segments and a
coloured overall STATUS on the DONE line are now SGR-coloured (green
pass, bold red fail/error, bold yellow warning).
Gating: -colour auto|on|off (default auto) colours only when stdout is
a real windows console, detected via twapi GetConsoleMode on the
STD_OUTPUT handle - the isatty-equivalent; get_console_handle proved
unsuitable (it succeeds for piped children of console shells, verified
both ways). NO_COLOR honoured in auto. Machine output (RUNTESTS_RESULT,
json) is never coloured; piped output stays plain for agents (verified
zero escape bytes piped, codes present with -colour on). Raw literal
SGR is used rather than a+/a so the runner's indicators are independent
of punk::console's process-global colour state (the same 2026-07-19
console runs showed that state shifting under mixed tty-ness). The
previously UNCONDITIONAL raw-red errorInfo block in the file-error
branch now goes through the same gate, so piped error output is cleaner
than before.
Also sharpens the -jobs guidance wording: subtree runs (e.g 28-file
modules/punk/args/**: ~50s sequential vs ~11s at -jobs 16) benefit from
-jobs - only single-file/few-file runs do not.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
dynamic_bad_tag_warns_once failed (count 0) ONLY in console-attached
singleproc runs (user report; reproduced deterministically with stderr
on a real console and stdout redirected): when stderr is backed by a
windows console channel, a pushed chan transform receives the console
driver's utf-16le wide-char byte stream - every ascii char arrives
NUL-interleaved, so content regexps never match. The punk::args warning
itself emits correctly, exactly once, inside the capture window (proven
with marker writes: markers and warning all captured, all wide).
Piped/file stderr and -jobs child processes deliver plain bytes, which
is why every piped run passed.
Fix in all three capture_stderr helpers (punk/args dynamic.test,
punk/ansi grepstr.test, punk/ns corp.test - identical latent defect):
if the captured data is NUL-interleaved, decode it as utf-16le
(fallback 'unicode' for tcl 8.6) before returning. Verified: the
console-attached args subtree run is green (246/243/3/0); piped runs
unchanged.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-measured reference-machine numbers 2026-07-19: -jobs 8 ~79-86s,
-jobs 16 ~61s (~5.6x vs ~5m40s sequential), plateau by -jobs 24 (~60s).
Guidance now recommends -jobs 16 and records the plateau anatomy
(slowest single child ~31s runtimecmd pair, serial console tail ~16s
piped / larger under a real console, ~10s runner overhead).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The '### runtests DONE at <ts>' human line gains '(elapsed <N>s)', the
RUNTESTS_RESULT summary line gains a trailing elapsed_seconds=<N>
key=value, and the json report gains a top-level "elapsed_seconds"
field - matching the name already used by the watch-mode run-end event,
which now shares the same computed value. Additive only; the parity
tool reads named keys and is unaffected (verified on all three report
styles).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
multishell.test (10 tests, ~105s solo child - the -jobs floor) split five
ways along shared-fixture boundaries, every test moved verbatim with its
provenance lines: multishell.test keeps wrap + structure/LF-only + exec
smoke (incl WSL); multishell_wrapverify.test (fresh-wrap checkfile) and
multishell_wrapdeterminism.test (byte-identical re-wrap) each re-pay the
wrap fixture; runtimecmd_checkfile.test and runtimecmd_roundtrip.test
guard the committed bin/runtime.cmd and its source round-trip with no
wrap fixture at all. argparsingtest.test (17 tests, ~32s) split into
timeit/discover/contract/first_call (11) + argparsingtest_compare.test
(compare_*, 6). Assessed and left unsplit: dtplite.test (24.6s solo),
scriptexec.test (12s); exec.test excluded as imported core material.
File headers point at the src/tests/modules/AGENTS.md punk/mix bullet
for the sibling map; the runtests longest-first weight table carries
measured post-split weights.
runtests_parity.tcl gains a -names mode: multiset comparison of
'- testname:' lines from '-report markdown -show-passes 1' captures,
file attribution ignored - verbatim moves compare identical, lost/
duplicated/renamed tests are reported.
Verified (native tclsh 9.0.3): repeated -jobs 8 full-suite runs 1m26.3s
/ 1m26.8s (was 2m16s at G-091, ~5m40s sequential - 4.07x vs the
pre-parallel baseline, 36.6% vs the G-091 reference); slowest child
30.7s / 31.3s (bound 45s); NAMES identical (989 occurrences) vs the
pre-split sequential capture; tallies identical in every run (989/973/
15/1, exec-14.3 sole failure, files 87 -> 92); PARITY ok -jobs 8 vs
-jobs 1 and between repeats; repo clean after runs. Notable finding
recorded in the goal file: child-wall contention inflation (~45% with
50s+ dominant children present) collapsed to ~15% once the work
distribution was flattened - splitting reduced both the critical path
and the contention itself.
G-092 flipped to achieved 2026-07-19 and archived (GOALS-archive.md
record, detail file with full verification evidence to goals/archive/).
goals_lint clean. Also noted in the goal file, out of scope: runtests
-include-paths multi-pattern/repeated-flag matching misbehaved during
measurement (single value with four deep patterns matched one; repeated
flags matched zero) - contradicts documented semantics, needs its own
investigation.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
-jobs N (implies -singleproc 0; explicit -singleproc 1 conflicts) runs
test files through a tpool of N concurrent child processes with
per-child capture files and tcltest -tmpdir subdirs, longest-first
static-weight submission, and a -serial-paths serial tail (default: the
console-state suites modules/punk/console/** + modules/opunk/console/**;
piped-child-driven suites proved parallel-safe and each serial file
costs its full child boot strictly after the parallel phase). Cached
results feed the unchanged processing loop in discovery order, so
reports are identical in shape and order to sequential runs. Watch mode
emits file-collected events (completion order, output relayed there);
file-end (tallies) stays discovery-order. The runner now reports jobs
phase times and the ten slowest child WALL times (child wall includes
boot + file-level fixture cost that per-test usec misses).
Two Tcl-core-level behaviours found and worked around in the child
spawn (see the verification record in the archived goal file):
- concurrent BLOCKING execs from worker threads convoy on Windows (all
return at the longest concurrent child's exit; plain sleepers 2-12s
from 8 workers all walled at 12.0s) -> spawn via 'exec ... &' and
poll per-pid tcl::process status; blocking fallback retained for
runtimes without tcl::process (tcl 8.6).
- Tcl_ReapDetachedProcs runs on every exec and purges finished
background children process-wide, racing the poll (nondeterministic
'key <pid> not known in dictionary') -> tcl::process autopurge false
+ explicit per-pid purge after the status read.
Verified on native tclsh 9.0.3: repeated -jobs 8 full-suite runs
2m16.2s / 2m15.6s with PARITY ok vs -jobs 1, between repeats, and vs
the pre-parallel baseline (987-test identity, exec-14.3 sole expected
failure); 2.58x vs the ~350s sequential baseline (2.41x vs one
cooler-machine 5m28.8s sequential run - recorded in the goal file);
repo clean after every run.
G-091 flipped to achieved 2026-07-19 and archived (entry to
GOALS-archive.md, detail file to goals/archive/ with the verification
record; reference sweep updated runtests.tcl comments and the
src/tests/AGENTS.md marker). goals_lint clean.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Convert punk::config from a manually-versioned module (config-0.1.tm) to
the standard magic-version scheme (config-999999.0a1.0.tm +
config-buildversion.txt, real version 0.2.0) per user direction -
punk::config was never in src/modules/AGENTS.md's manual-versioning
exception list (punk::libunknown, punk::mix::base only). No callers pin
the old version; built/bootsupport/vfs copies remain 0.1 until the next
make run, as usual.
Includes the user-authored registration of PUNK_TEST_UDPTEE in the known
punk env vars table (runtests UDP watch mode / runx -teelog, a65f9e5b -
see src/tests/AGENTS.md). CHANGELOG 0.15.0 entry extended accordingly.
Verified: package require punk::config resolves 999999.0a1.0 under the
dev module paths (package prefer latest); focused runtests spot run
green. The env vars table is materialized inside the config init proc,
so registration is exercised at shell boot rather than package load.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
runx -teelog {-tag/-syslog/-file/-raw settings}: live tee of the
captured stdout/stderr to shellfilter::log workers (log sources
<tag>stdout/<tag>stderr) while captured/returned data is unchanged.
Implemented as write traces on the capture variables rather than extra
channel transforms: probing showed a tee_to_log float combined with the
float-locked capture junction is starved or loses its worker settings
through add/remove churn (float-placement logic is unaudited - README
'very unripe parts'), and shellthread's parked-worker adoption does not
re-apply settings (writes silently misroute to a previous target). Both
findings deliberately not addressed here - recorded for a proposed
shellfilter/shellthread audit goal. Tag workers stay open for reuse;
conflicting reconfiguration errors explicitly.
runtests.tcl watch mode: env PUNK_TEST_UDPTEE=<port>|<host>:<port>
streams runner lifecycle events (tag 'runtests', tcl-list
RUNTESTS-EVENT messages: run-start/file-start/file-end/run-end with
tallies) and test output (tags teststdout/teststderr) to a local UDP
listener via the same mechanism - live per chunk in singleproc mode
(runx -teelog inside the testinterp), relayed per completed file by the
parent in multiproc mode. Watch mode terminates the per-testinterp log
worker threads after each file; unwatched runs are unchanged (including
the pre-existing teehandle-worker leak, also noted for the audit). The
parent extends auto_path with <projectroot>/lib_tcl<N>/<arch> so
workers load tcludp 1.0.13+ (1.0.12 UDP_ExitProc = G-036 exit-hang
class).
Verified on native tclsh 9.0.3: full-suite result parity (87 files, 989
tests, exec-14.3 sole failure) for watch-off and watch-on singleproc
runs vs the pre-change baseline; focused watch runs in both modes
captured over UDP (events + live/relayed output). Viewer-side caveat
documented: tcludp's receive fileevent under Tcl 9.0.3/Windows
delivered only the first datagram (send side unaffected; .NET UdpClient
received all).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Multi-process mode previously execd bare test files with no environment
(children died on their first package require) and misreported the
crashes as missing-cleanupTests warnings with the stderr discarded.
- testsupport/child_test_runner.tcl (new): per-file child bootstrap.
Applies a runtests-generated environment payload (prefer latest, test
tm paths, auto_path, modpod ifneeded defs, tcltest options; per-file
-testdir computed child-side), warms 'clock format' before the
module-path wipe (first script-level clock use loads msgcat from the
runtime default paths, which the test paths do not supply), and
mirrors the testinterp preload: package require shellrun plus one
no-op runx -tcl call (runx execution pulls punk::lib; several suites
depend on preloaded punk::* commands).
- runtests.tcl: generate the payload per run; spawn children via plain
exec with file-captured stdout/stderr and immediate-EOF stdin
(mechanism reusable for future parallel -jobs scheduling); classify
nonzero child exits as file-level failures with the stderr tail
surfaced in all report styles (exit-0-no-summary remains the
missing-cleanupTests warning); warn under kit executables (children
boot with kit-stamped punk packages preloaded, shadowing src dev
modules - prefer a native tclsh).
- scriptlib/developer/runtests_parity.tcl (new): compares two
'-report json' captures on result identity (per-file counts,
failure/skip/warning identities; timings ignored), tolerating
preamble noise and the ANSI SGR reset emitted on the JSON line.
Verified on native tclsh 9.0.3: full suite singleproc vs multiproc
PARITY ok (87 files, 989 tests, 973/15/1 with the documented exec-14.3
baseline as the sole failure); crash and warning classification
exercised. Wall time ~5m50s in both modes.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Refresh via make.tcl modules + vfscommonupdate after the argparsingtest
1.0.0 restructure: _vfscommon.vfs swaps argparsingtest-0.2.0.tm for the
version-stamped 1.0.0 build. argparsingtest is not in the bootsupport
include_modules.config, so no bootsupport snapshot is affected (the
stale src/bootsupport/modules/argparsingtest-0.1.0.tm remains a known
prune leftover). Kit builds (make.tcl project) not run this change-set.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Restructure of the parser-timing module around three calling styles:
- parser procs move into per-style child namespaces argparsingtest::opts /
::tkstyle (2 leading positionals) / ::tclstyle (2 trailing positionals),
with identical short proc names across styles; the test1_ prefix is gone
- hand-rolled parsers share a manual_ prefix (manual_ni, manual_switch,
manual_prefix, ...) so they group visually in the comparison tables;
test1_prefix2 removed (not meaningfully distinct from test1_prefix)
- tkstyle/tclstyle carry a representative roster (manual_switch baseline +
punkargs/punkargs_by_id/punkargs_parsecache + opt + cmdline + tepam);
style parsers return a {p1 p2 opts} list
- new 'unsupported' discovery status for library/style combos the backing
library cannot express: cmdline with leading positionals (getoptions stops
at the first non-option word - probe verified), argp with any positionals
(parseArgs walks the whole list as option pairs - source verified).
compare renders these as N/A rows below the timed rows so every library
still appears in every style's table
- harness procs (discover_parsers/timeit/first_call/compare) gain
-style all|opts|tkstyle|tclstyle and return results keyed by style;
-args requires a single -style (each style has its own default vector);
external probe keys drop the test1_ prefix (getopt/parse_args/argparse/cmdr)
- punkargs_by_id variants keep the eager punk::args::define as sole doc
source (the former duplicate argdoc lappend made the lazy namespace scan
undefine/re-register the id on first introspection); unused struct::set
require dropped; opt/cmdline/tepam requires hoisted to module top;
first_call library warm-ups extended with positional coverage
- test suite rewritten: 17 tests including per-parser {p1 p2 opts} contract
checks across both positional styles, N/A table rendering, roster counts
and the -style/-args error paths
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Batch refresh via make.tcl packages/bootsupport/vfscommonupdate: punk::path
0.2.2 -> 0.3.0 (extensionless lib: tcl identification - this change-set),
plus promotion of punk::args 0.12.6 and punk::ns 0.9.0 built at the previous
source commit. vfscommon lib copies of app-punkscript/app-punkshell/
app_shellrun pick up the shared scriptlib_resolve refactor. Includes the
project-layout bootsupport snapshot copies (punkboot-bootsupport installer).
Kit deploys to bin/ for punk91.exe and punk902z.exe were blocked by running
shell instances holding the executables (build reported the failed deletes);
rerun make.tcl project (or close the shells first) to deploy - tests were
run against the freshly built kit from src/_build.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
scriptlib_resolve now lets an extensionless (or unknown-extension) lib:<name>
call match a file named exactly <name> when its first lines identify it as
tcl: a leading '# tcl' comment (prefix, case-insensitive), a shebang naming
tclsh/tclkit/wish, or the portable sh-trampoline ('#!/bin/sh' with a
commented 'exec tclsh' continuation - detected within the first 4 lines).
New internal punk::path::system::scriptfile_is_tcl does the bounded sniff
(512 bytes, UTF-8 BOM and CRLF tolerated, directories/unreadable files
rejected). When both <name> and <name>.tcl exist, the spelling matching the
call wins, checked per scriptlib location so kit-internal directory
precedence is never crossed by a spelling preference.
.kit joins the known extensions: lib:<name>.kit previously had .tcl appended
(searched <name>.kit.tcl), which made the shell subcommand's do_tclkit
dispatch arms unreachable - lib: kit dispatch is now restored. Result dict
reworked: scripttype (tcl/kit/py/pl/ps1/sh or empty) + notes keys added,
scriptname is now the matched relative name, and matches require file isfile.
app-punkshell and app_shellrun lib: handling refactored onto the shared
resolver (previously independent inline copies of the policy), fixing two
silent-failure bugs in that copy: no message at all when a scriptlib dir
existed but lacked the script, and the error listing showing
<kit>/scriptlib rather than the <kit>/app/scriptlib actually checked.
app-punkscript's post-resolve gate now uses scripttype and its not-found
report includes the identification skip notes. The unused has_globchars
vestige is dropped.
Fixtures scriptlib/_punktest/{extless,dual,dual.tcl,shebang_sh,notatcl} and
5 new scriptexec.test cases (extensionless resolve, both precedence
directions, trampoline shebang + argv, non-tcl skip note on not-found);
suite passes 17/17 against a freshly built punk902z kit. Sniff helper unit
checks pass under tclsh 9.0.3 and 8.6. punkshell project 0.13.0 -> 0.14.0.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
punk::ns 0.9.0: cmdhelp (i) gains -return text - plain-text argument
documentation for machine/LLM consumption: no ANSI, no table layout, the
argument section of every command form rendered in one output under a common
header ('i -return text after' shows all six forms), G-041 form selection
still honoured when argument words are supplied, no advisory-parse error
preamble (-return dict remains the parse-status surface). Implementation
delegates resolution to the -return dict recursion and renders per-form via
the string renderer.
punk::args 0.12.6 (user direction; string-form layout explicitly not frozen -
no external consumers yet):
- arg_error renders the error message + per-form match detail exactly once,
BELOW the usage display (was above and below); bottom append suppressed for
empty messages.
- string renderer argument rows are single-line
'name TYPE:type(constraints) ?DEFAULT:'val'? ?MULTI:yes?' - type
constraints parenthesize onto the base type instead of line-breaking
mid-row; empty DEFAULT/MULTI labels and whitespace-only help blocks omitted.
- choices render as markdown-subset bullets '- `choice` - label' with label
continuations at a fixed deeper indent - choice names are now
machine-distinguishable from label text without ANSI. Structural contract:
column-0 lines bearing TYPE: are argument rows, indented lines are
documentation, backticked bullets are choices. Table cells unchanged.
New scriptlib/developer/whatis.tcl (runtime command introspection for
agents): resolved name, subcommand-chain resolution via punk::ns::cmdinfo
('whatis string is'), kind, providing package + loaded version, origin file,
proc definition file:line, punk::args synopsis; -body appends the runtime
body with file-relative line numbers, -doc the full plain-text argdoc via
cmdhelp -return text (with fallback for older punk::ns). Backing the
cross-framework tcl-whatis agent skill: canonical .agents/skills/tcl-whatis/
(Agent Skills standard - pi/OpenCode/Codex) with byte-identical copy in
.claude/skills/ for Claude Code; .gitignore gains !.claude/skills/ with the
fossil ignore-glob comment + exception-set docs updated per the dual-VCS
contract (fossil adds staged). Root AGENTS.md: .agents/skills index entry,
whatis pointer in Repo-wide Notes, scriptlib/developer example.
Tests: new pins cmdhelp_return_text_all_forms/_argword_form_selection/
_single_form_plain_marker (cmdhelp.test), rendering_stringmode_singleline_argrows
+ rendering_stringmode_choice_bullets (rendering.test); deliberate-change pin
updates: errorselection.test message matches gained leading * and cmdhelp.test
message pins sample the last line (message placement). Full source-tree suite
963/979 pass, sole failure the pre-existing exec-14.3 baseline; make.tcl
modules clean.
Project version 0.12.42 -> 0.13.0 with CHANGELOG.md entry.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl modules/bootsupport(x2, 2nd pass copied 0)/vfscommonupdate/project
sequence per the workflow overview. Kit vfs payload and bootsupport module
sets (incl project_layouts bootsupport copies) updated to the new built
versions; superseded 0.12.4/0.8.0/0.1.0 copies removed.
Kits: punkbi.exe and punksys.exe rebuilt and deployed (punksys verified
carrying 0.12.5/0.8.1/0.2.0); punk91.exe and punk902z.exe deployment skipped -
target binaries in use by running shells - redeploy after closing them.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
parse -cache overhaul:
- VALIDATION trap's parse_cache write now explicitly gated on -cache (formerly
unconditional but landing in a discarded proc-local for -cache 0 by scoping
accident - 'variable parse_cache' only ran on the -cache 1 branch)
- cached validation errors stored as per {errorstyle callertext} render
variants under a {arglist definition form} main key (-caller dropped from the
main key - results don't depend on it); a missing variant falls through to a
fresh render. Previously the first caller's errorstyle and %caller%
attribution were baked in and replayed verbatim to later callers.
- @dynamic definitions (and legacy leading '-dynamic 1') are never cached so
re-evaluated substitutions always take effect; dev/dynamic-cache.test
known-bug pin flipped
- new punk::args::parse_cache view/clear proc (sgr_cache style); guarded
variable init; -errorstyle definition default corrected to the operative
'standard'. New parsecache.test (7 tests).
synopsis notation + internal @form -synopsis retirement:
- ::punk::args::parse/::parse_status dropped their stale @form -synopsis
overrides (omitted -cache/-caller) for auto-generated lines shaped with
-typesynopsis {<int|formname>...} on -form; drift pin
synopsis_parse_generated added
- punk::ns::synopsis no longer errors on custom @form -synopsis lines that are
not valid Tcl lists (e.g Tcl manpage style '?-form {int|<formname>...}?' -
's parse' raised 'list element in braces followed by ...'): non-list lines
take a textual command-head replacement fallback
- @form -synopsis directive help rewritten (display-only, any style, prefer
auto-generation, known warranted case: script-level/constructed ids);
::punk::args::synopsis -help gains a notation legend and a new @examples
block comparing Tcl man-page ?...? style with the bracket style (punk::args::eg)
eg usability + examples indication:
- punk::args::eg resolves relative/unqualified command names (punk::ns::cmdinfo
from calling context when loaded, else global qualification) - in namespaces
where it shadows the global 'eg' alias (e.g ::punk::args) 'eg list' returned
empty while 'i list' worked; unknown ids now return a message naming the id;
punk::ns::eg hands the typed name through on unresolved docids
- usage-table 'Example: eg <id>' header row now uses scheme colour CLR(check)
(interim display until G-088 footer/subtitle support)
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New procs timeit/compare/discover_parsers/first_call for rough cross-parser
performance comparison (punk::args variants vs hand-rolled dict/switch/prefix,
tcllib opt/cmdline/tepam, argp), with PUNKARGS argdoc coverage throughout.
first_call times each parser twice in fresh child interps:
- cold: first call after package load (includes byte-compilation of the parser
proc body and any backing-library procs it invokes)
- warm: the backing library is pre-exercised via per-library sacrificial
warm-up scripts (library_warmups dict) so the timed call isolates per-proc
first-use cost. Replaces an earlier punk::args-only
'punk::args::parse {} withdef {}' warm hack that was unfair to the other
libraries under test and only partially warmed punk::args itself.
Child interps pin package requires to the parent's loaded versions
(punk::args, punk::lib when present, argparsingtest) - plain package require
prefers stable versions, so children otherwise timed older stable copies
visible on the module paths instead of the dev module under test; under
Tcl 8.6 the punk::lib pin also supplies the lpop compat shim punk::args::parse
needs, unbreaking punk::args timing in bare child interps there.
compare renders first_cold/first_warm columns (table), nested cold/warm
sub-dicts (dict/json). New test suite under src/tests/modules/argparsingtest.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Prints the release-ready command sequence, source -> built-packages ->
bootsupport / kit-vfs / kit-executable folder-flow diagrams, and keyed notes
(magic-version stamping, punkcheck provenance, staleness gate, -confirm
policy, locked-exe deploys, VCS-tracked output targets). The text is embedded
in make.tcl (::punkboot::workflow_text) rather than a data file so it travels
with the make.tcl copies seeded into generated-project layouts; content is
project-generic accordingly. A MAINTENANCE key in the output states the
update contract.
punk::args-documented via the existing constructed-definition machinery
(SUMMARIES/HELPTEXTS/SUBOPTS + informational SUBGROUPS entry) so tabled help,
'help workflow' and the top-level subcommand table all cover it; also
registered in known_commands and the plain punkboot_gethelp fallback, and
exempted from the bootsupport staleness gate alongside check/projectversion.
Verified in normal and PUNKBOOT_PLAIN dispatch; stray arguments raise a
punk::args toomanyarguments usage error; output is pure ASCII, width <= 100.
src/AGENTS.md Work Guidance gains the agent update contract: change the
workflow text in the same change-set as any build data-flow change, keep the
ASCII/width/structure rules, verify with 'make.tcl workflow' (+ one
PUNKBOOT_PLAIN run), and the registration-point checklist for subcommand
changes. Layout make.tcl copies propagate via 'make.tcl bootsupport' - never
hand-synced. punkshell 0.12.42.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl vfscommonupdate -confirm 0 after the 0.12.4 modules build. Besides
punk::args 0.12.3 -> 0.12.4 (collision-aware resolve miss path), the REPLACE
pass brought _vfscommon.vfs up to date with built modules that had not been
propagated since the 0.12.37 refresh: cap handlers templates 0.2.0, mix
base 0.1.1, mix commandsets layout/module/scriptwrap 0.1.1 + project 0.2.2,
mix templates 0.1.5, fauxlink 0.1.2/0.2.0, tomlish 1.1.12 + test module
catch-up (test/tomlish-1.1.5 content matches built copy).
make.tcl project -confirm 0 rebuilt the kits: punkbi.exe and punksys.exe
deployed to bin/; punk91.exe and punk902z.exe builds succeeded but
deployment to bin/ was blocked by running shell instances holding the
binaries (fresh kits left in src/_build - redeploy after closing shells).
Kit executables are not tracked; this checkin is the vfs source tree only.
argparsingtest work (module 0.2.0, tests) deliberately left uncommitted;
its derived vfs artifacts (argparsingtest-0.1.0.tm removal / 0.2.0.tm
addition) are likewise excluded from this checkin.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
resolve's first-sighting path for a rawdef whose @id is already registered
with different content now purges the id's existing cache entries (quiet
undefine) before registering, mirroring define's re-creation behaviour.
Previously it repointed id_cache_rawdef while stale rawdef_cache_about /
rawdef_cache_argdata entries lingered - two rawdefs claimed the same id and
a subsequent define with the original text was a silent no-op (stale
cache-about hit), leaving withid lookups stuck on the inline definition.
The disabled blanket "called with undefined id" stderr warning is removed -
it flagged supported inline usage (parse ... withdef, direct resolve
calls). Guard checks id_cache_rawdef directly (id_exists also matches
aliases, where the rawdef lookup would error). Known residual: the miss
path still records no -defspace for @dynamic definitions first seen via
resolve.
New define.test pin define_resolve_id_shadow (characterized pre-fix: the
re-define no-op reproduced with the purge disabled). punk::args suite green
under Tcl 9.0.3 (228 passed, 0 failed). punkshell 0.12.41.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The layout custom/_project bootsupport sync picks up files newly arrived in
src/bootsupport on the following run (same two-pass propagation as the guarded
prune tooling); punk.project-0.1 and punk.shell-0.1 copies now carry the
stage-2 handler/modpod versions with the superseded copies pruned.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl bootsupport refresh following the stage-2 cutover; superseded 0.1.1
handler and 0.1.4 modpod pruned (the modpod copy required manual deletion -
the running make.tcl mounts it and the prune self-locks; flagged in the G-087
detail file). Layout custom/_project bootsupport copies mirrored by the build.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
punk::cap::handlers::templates 0.2.0: layout refs are fauxlink files
(<alias>#<encodedtarget>.fauxlink|.fxlnk, target relative to
<projectroot>/src/project_layouts, resolved via the fauxlink module).
get_itemdict_projectlayoutrefs selects *#*.fauxlink/.fxlnk with fauxlink-derived
names; get_itemdict_projectlayouts derives the layout folder from the resolved
targetpath; the <alias>@<target>.ref parser is removed and .ref files are no
longer recognised. Alias-less (leading-#) refs and unresolvable refs are
skipped with a warning - punkcheck-based tooling excludes leading-# filenames,
so layout refs must carry a non-empty nominal name. Also fixes the ignore*
skip, which previously matched against the full glob path and never applied.
All 7 live-tier refs renamed via a fauxlink::link_as-driven migration script
(each generated name round-trip-verified through fauxlink::resolve before
rename): decktemplates vendor/punk x4 (alias-less refs gained their target-tail
aliases: basic, minimal, sample-0.1), custom/_project x2, and the
module-shipped modpod ref (punk::mix::templates 0.1.5). Zero-byte property and
all visible layout names unchanged. src/project_layouts/README.md ref-grammar
section rewritten for fauxlink.
Note: git's rename pairing crosses two of the zero-byte vendor/punk refs
(sample-0.1 <-> project) - content-identical empty files; the true mapping is
alias-preserving as described above.
Verified: stage-2 scratch checks 7/7 (name parity incl exact punk.project,
decoy alias-less ref warned+skipped, old-grammar decoy ignored); runtests
prune/fossilmove/multishell/libsearch pass; end-to-end dev project.new
materializes a full project from the default punk.project layout.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl bootsupport: fauxlink 0.1.2 -> 0.2.0 in src/bootsupport and the
custom/_project layout copies; superseded 0.1.2 pruned, along with the layout
copies' templates-0.1.3.tm prunes deferred by the earlier transient lock.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
make.tcl bootsupport batched build-output refresh (punkcheck-managed): fauxlink
0.1.1 -> 0.1.2, plus catch-up of source versions that had moved since the last
refresh - punk::ansi 0.1.3, punk::args 0.12.3, punk::lib 0.5.0, punk::ns 0.8.0,
punk::repl 0.5.2, tomlish 1.1.10 -> 1.1.12, test/tomlish-1.1.5 modpod, and this
morning's G-087 hygiene bumps (cap handlers templates 0.1.1, punk::mix::base
0.1.1, commandset layout/module/scriptwrap 0.1.1, commandset project 0.2.2,
punk::mix templates 0.1.4). Superseded versions pruned; the same refresh is
mirrored into the custom/_project layout bootsupport copies by the build.
templates-0.1.3.tm prune initially failed with a transient file lock and was
removed manually after verification.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Pulled by the same vendorupdate run from the clean tomlish upstream checkout
(c:/repo/jn/tclmodules/tomlish): tomlish 1.1.12 added alongside earlier
versions per existing practice; test/tomlish-1.1.5.tm modpod refreshed in
place from its source.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Vendored from the now-committed upstream project (c:/repo/jn/tclmodules/fauxlink,
checkins c82c9bb9 + ed1eebdb): punk::args documentation blocks including a
(package)fauxlink id (inert PUNKARGS + registration, no punk::args dependency;
full surfacing awaits G-075), decode_unicode_escapes hexless-%U first-char-drop
fix, 3-segment comment validation/decoding parity, link_as stub now errors
instead of silently no-oping, and a 62-test upstream suite (src/tests/fauxlink.test)
covering resolve/decode behaviour and the documentation metadata.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Two independent list-flattening bugs made `runtests.tcl foo.test bar.test`
match zero files, forcing agents to run files individually:
- the trailing glob value is -multiple 1, so its parsed value is a list;
plain lappend nested it as a single space-containing element
- punk::path::treefilenames declares tailglobs as a -multiple 1 positional
(one glob per argument), but the whole file_globs list was passed as one
argument, re-collapsing it (this also broke multiple globs supplied via
-tcltestoptions {-file {...}})
Single names always worked because a one-element Tcl list flattens to
itself, which masked both bugs. Verified: two file tails now discover and
run both suites (files=2, 40/40 pass).
Also note multi-file-tail support in src/tests/AGENTS.md Work Guidance.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- punk::mix::templates modpod (0.1.4): dead templates/layouts/project payload
subtree removed - design-generation residue with no reader; layout payloads
live in src/project_layouts, located via layout_refs.
- src/make.tcl: unused old_layout_update_list (referencing the long-gone
src/mixtemplates and modules/punk/mix/templates paths) removed; bootsupport
help text now names src/project_layouts/custom/_project/<layoutname> instead
of mixtemplates.
- src/project_layouts custom/_project make.tcl copies: punkcheck-managed sync
outputs refreshed by the verification 'make.tcl modules' run.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- @vendor+punk+project-0.1.ref renamed to project@vendor+punk+project-0.1.ref:
the alias yields the exact layout name 'punk.project', so project.new's
defaulted -layout resolves unambiguously (previously tcl::prefix::match saw
only punk.project-0.1 / punk.project-0.1_overrides).
- Junk/test refs removed from the selectable layout list: test2, the
custom/_project duplicate sample-0.1 ref, and the alias-less punk.shell-0.1
ref whose target was an a.txt-only folder (folder removed too; the real
shell layout remains exposed as punk.shell-0.1_overrides).
- src/project_layouts/README.md rewritten to describe the implemented
punk.templates + layout_refs mechanism including the ref filename grammar,
the not-yet-implemented overlay semantics, and a G-087 pointer; the dead
punk.projectlayout capability description is gone.
Layout names after this change: punk.sample-0.1 punk.project punk.minimal
punk.basic punk.shell-0.1_overrides punk.project-0.1_overrides.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- put -> puts at all six no-handler warning sites (commandset layout x2,
project, module, scriptwrap, mix/base get_template_basefolders - the sweep
found three sites beyond the review's list). Three procs also dereferenced
an unset result variable after the warning; the no-handler paths now warn
and return an empty dict. layout references_as_dict and module templates_dict
warning messages no longer misattribute their owning proc.
- punk::cap::handlers::templates: brace the absolute-pathtype existence test
('if {!file exists $normpath}' raised an expr syntax error on any
absolute-pathtype provider registration), and add the missing dict-exists
check in pkg_register's duplicate-registration guard (errored 'key not known
in dictionary' for any second provider package registering a capability).
- Versions: commandset layout 0.1.1, project 0.2.2, module 0.1.1,
scriptwrap 0.1.1, cap handlers templates 0.1.1; punk::mix::base 0.1 -> 0.1.1
(manually versioned: file renamed, provide block updated, history comment
added).
Verified: scratch no-handler/registration checks 13/13 (see
goals/G-087-thin-project-layouts.md Progress); runtests prune/fossilmove/
multishell/libsearch all pass; make.tcl modules builds clean.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The old Tk dll set aside during the punk9win.vfs split is no longer
wanted in the tk903 kit payload; the 9.0b2-era dll remains available in
punk9wintk90b2.vfs.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Closes the loophole flagged in the 6.22 -> 7.11 swap: with the .tm
files deleted, a future make.tcl vendorupdate would have regenerated
them from these entries. tablelist now ships solely as the
src/vendorlib/tablelist7.11 pkgIndex lib.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New vfs_startup_script_warning check runs for each .vfs folder about to
be built against a runtime: it passes if the folder has a root main.tcl
or a root fauxlink resolving to the name main.tcl whose target exists
and is a .tcl file. Otherwise a noticeable warning is emitted and the
build proceeds (a kit with no startup script is legal).
Warnings use a new general-purpose ::punkboot::print_build_warnings
channel: column-0 BUILD-WARNING: token for greppability, ANSI highlight
for humans, and recap at end of run via the wrapped ::exit (same
treatment as PROVENANCE-WARNING). Overlay-only folders with no runtime
mapping (e.g _vfscommon.vfs) are not checked. Contract documented in
src/vfs/AGENTS.md.
Motivated by the punk9win.vfs split initially dropping the main.tcl
punk_main fauxlink from punk9wintk90b2.vfs.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Adds the main.tcl fauxlink omitted from the punk9win.vfs split, and
points the commented-out tclsh90b2/tksfe-twapi-x64 mapvfs.config
entries at the new kit names.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Remove src/vendormodules/tablelist-6.22.tm and tablelist_tile-6.22.tm
in favour of the multi-file src/vendorlib/tablelist7.11/ (pure Tcl,
upstream layout with pkgIndex.tcl). _vfscommon.vfs follows via
make.tcl vfscommonupdate: modules/tablelist*-6.22.tm removed,
lib/tablelist7.11 added.
Note: src/vendormodules/include_modules.config still lists the
tablelist/tablelist_tile module sources; a future make.tcl
vendorupdate would regenerate the 6.22-era .tm files unless those
entries are removed.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Replace the single punk9win.vfs payload with two per-Tk-version kits:
- punk9wintk90b2.vfs: content-identical copy of punk9win.vfs (same Tk
9.0b2-era bin/tcl9tk90.dll) except the main.tcl punk_main fauxlink
was not carried over (kit is parked; its tclsh90b4_piperepl mapping
remains commented out in mapvfs.config)
- punk9wintk903.vfs: same payload with a newer Tk bin/tcl9tk90.dll
(Dec 2025 build, Tk 9.0.3) and the old 9.0b2-era dll set aside as
bin/tcl9tk90xxx.dll; adds lib_tcl9/apave4.4.10 (pure Tcl); drops the
modules_tcl9 Thread-3.0b3 modules (Thread is static in the tclsfe
runtime); now the mapping target for tclsfe-x64.exe (punk91 kit)
src/runtime/mapvfs.config and src/runtime/vendorlib_vfs.toml (tcludp
install targets) retargeted from punk9win.vfs to the new kit names.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
User-directed removal of the two pipeline-based development iterations flagged
as candidates in the 0.7.0 hygiene pass. Both were undocumented, unexported
global aliases superseded by the plain proc nscommands (which adds
weird-namespace handling); no callers existed in the repo and nscommands1 was
broken - it referenced nonexistent commands (nsthis2, inspect at global
scope) and errored on first use. Recoverable via git history.
ns/nav/repl suites 111/111 green. buildversion 0.7.1 -> 0.8.0 (command
removal); project 0.12.36 + CHANGELOG (patch - the aliases were never part of
the documented shell contract).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The -return summarydict choicelabel claimed the linemap key appears only when
-n is supplied - actual behaviour (pinned in ansi/grepstr.test since the
characterization wave) is that linemap is always present. Help text corrected
to match; deferred-to-the-hygiene-pass item from the grepstr characterization.
ansi suites 63/63 green. buildversion 0.1.2 -> 0.1.3; project 0.12.35 +
CHANGELOG.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Both fixes were pinned as known warts before the change; the pins flip with it:
- get_nslist: the -types default sat inside a braced dict-create literal, so it
was the literal string $known_types - any call without -types (notably bare
user-level `nslist`) errored with the malformed "Unrecognised namespace
member type: $known_types". An unsupplied -types now defaults to all known
member types. Pin flipped: nslist.test nslist_types_default_error_QUIRK ->
nslist_types_default (bare nslist renders children + commands). nslist's own
PUNKARGS -types gained help text, deliberately without a -default so the
passthrough stays absent when unsupplied.
- nsjoinall: the non-empty-prefix-vs-absolute-path error message carried a
copy-paste "nsjoin:" prefix - now "nsjoinall:". Pin flipped in
nsprimitives.test nsjoinall_edges.
- nscommands: commented out a development trace puts (">>> base: ...") that
polluted stdout on the weird-namespace path (same treatment as the 0.1.1
doc-lookup trace-puts cleanup; not pinned).
Suites green: ns/nav/repl 111/111; full source-tree run at the known baseline
(only core exec-14.3, pre-existing). buildversion 0.7.0 -> 0.7.1; project
0.12.34 + CHANGELOG.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
No change to shipped behaviour (ns+nav+repl suites 111/111 green). Minor bump
because unused procs were removed.
Removed (~1200 lines, recoverable via git history):
- the fully commented-out predecessor help command arginfo (~930 lines) -
its own header marked it replaced by cmdhelp
- superseded/deprecated name-primitive twins nsparts1, nsprefix1,
nsprefix_orig, nstail1, nstail_orig (never exported, no callers; NOT
drop-in equivalents - divergence on 5+ colon runs was pinned in
nsprimitives.test before removal; those divergence pins are removed with
the twins and replaced by a direct nsprefix long-colon-run pin - the
divergence record lives in the test file history, commit 0c7168a1)
- obsolete nsglob_as_re1, empty stubs ns_relative_to_location/
ns_absolute_to_location, obsolete internal::_pkguse_vars, an if-0 block in
nstree_list, unused interp_aliases assignment in get_ns_dicts, assorted
commented-out remnants (pre-punk::args defaults blocks, pipedata width
calcs, corp default-retrieval experiments, cmdtrace trace-add alternates)
Documentation accuracy:
- nsprefix comment corrected (:::a prefix is :: not ::a - per pins)
- nsglob_as_re stale "should be fixed" note replaced with an accurate
description of the in-place negative-lookahead fix (* matches an inner
single colon, never crosses ::)
- nstree_list previously empty PUNKARGS summary/help fields filled
- nstail gained a doc comment; nseval_ifexists gained the native-vs-punk
p:::x divergence note; the dangling "string functions" sentence completed
- cmdhelp help typos (auto-gnerated, commands commands); corp -syntax help
truncated sentence completed
Flagged, deliberately unchanged (comment only):
- get_nslist red-strike/masked alias display branches appear unreachable
from current bucket derivation (nslist.test fixture findings) - reassess
at the planned display rework
- nscommands1/nscommands2 pipeline aliases: superseded removal candidates
(nscommands1 errors on first use - references nonexistent nsthis2)
- cmdtrace stdout/stderr noise deferred to proposed G-085
- test_switch* marked as live cmdtrace test fixtures (used by cmdtrace.test)
All inserted/updated comments carry 2026-07-14 Agent-Generated/Agent-Updated
marks. buildversion 0.6.0 -> 0.7.0. Known-wart fixes sanctioned by the pinned
backlog (nslist -types default, nsjoinall error prefix) follow separately.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New shell/testsuites/punkexe/shellnavns.test - one hang-proof punk_run piped
session against the built executable in src launch mode (dev modules, so
current punk::repl/nav source is exercised without a rebuild):
PROVEN end-to-end:
- n/ sets ::punk::nav::ns::ns_current in the running shell
- the current namespace continues into `subshell punk` and back out, and the
0.5.2 stray-namespace seeding fix holds live (no phantom ns_current
namespace in the subshell context)
- navigation inside the subshell takes effect; the session exits cleanly
(exitcode 0, no timeout, exit unwinds subshell -> parent -> terminate)
FINDINGS from the E3 probes (pinned in the test with markers):
- the FIRST subshell evaluates in the SAME code interp as the parent shell -
the "first subshell asymmetry" already TODO-documented in repl::init.
Continuity therefore manifests via shared state at shell level (SHARED
marker: a variable set in the subshell is visible to the parent after
exit, and the parent adopts the subshell''s final namespace). The
repl::start seeding template - the carry-over mechanism for genuinely
separate code interps - is proven at module level in punk/repl
nscurrent.test. A G-002-style isolated subshell would flip these pins.
- KNOWN GAP: piped-session submissions evaluate at :: even after n/ sets
ns_current - the inscope application proven interactively and at module
level does not take effect for subsequent piped submissions in this spawn
shape. Root cause undetermined (piped-path evaluation vs kit/codethread
interplay); flagged for investigation alongside G-038 session-context
work.
Verified: shell/** suite 42 total / 40 passed / 0 failed (2 gated skips)
under Tcl 9.0.3. AGENTS updated (shell contracts bullet; punk/repl module
index E3 reference).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
