tcl-runtests (new): agent quickstart for src/tests/runtests.tcl.
Runner-interpreter policy: the zig-built suite tclsh
(src/buildsuites/_build/suite_tcl90/out/bin/tclsh90s; tclsh86ts for 8.6
parity) or a bin/runtime store tclsh; a fresh checkout bootstraps via the
no-tclsh 'zig build bootstrap' flow (pinned zig only, bin/punk-getzig) or
by fetching prebuilt runtimes from punkbin via bin/punk-runtime - which
path is the user's choice, not an agent default. Never bare 'tclsh' from
an agent shell (commonly the MSYS/Git-for-Windows one - spurious
failures); native tclsh preferred over punk kit exes (kit-stamped module
shadowing). Plus canonical invocation/targeting forms, result-reading
rules (status=warn = incomplete), agent-environment traps (NO_COLOR=1
breaks exact-SGR pins agent-side only; PowerShell-tool attached consoles;
no mid-run .test edits; PUNK_SHELL_TEST_EXE for locked/stale kit exes)
and .test authoring micro-traps (trailing 'set result', brace-in-comment
parse death, \y-not-\b). Pointer-first: src/tests/AGENTS.md remains the
authoritative harness contract.
tcl-whatis/tcl-nslist: one sentence added to the Command section - the
launcher one-liner form `bin/punk91 src script -e '<tcl>'` for RUNNING a
snippet rather than introspecting it (behaviour checks, cross-version
probes via the documented punk905/punksys kits).
Facts verified live before writing: suite tclsh90s = Tcl 9.0.5 + Thread
3.0.7 and drove a focused runtests run (args dynamic.test 2/2 PASS, 5s);
runtime-store tclsh9.0.5-punk/plain = 9.0.5 + Thread 3.0.7; -e forms on
punk91/punk905/punksys; punk-runtime list output; PUNK_SHELL_TEST_EXE
resolution in the punkexe suites.
.claude/skills copies are byte-identical re-copies of the .agents
canonicals (diff-verified) per the root AGENTS.md skill sync convention.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Julian Noble
9d92c11bd7