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
The skills pinned bin/punk91 but never stated which Tcl it embeds, and the
"any punkshell kit works" fallback was unqualified - Tcl-version-sensitive
introspection questions (e.g. 8.6-vs-9 builtin differences) left the agent
to work out kit versions unaided, in a bin/ full of non-kit exes.
Add one sentence to each skill's Command section: punk91 embeds Tcl 9.1;
for Tcl-version-sensitive questions, or if punk91 is unavailable, use
punk905 (Tcl 9.0) or punksys (Tcl 8.6) with the same command line. Stated
versions smoke-verified against the live kits (9.1b0 / 9.0.5 / 8.6.13).
Canonical .agents/skills copies edited; .claude/skills re-copied and
diff-verified byte-identical per the root AGENTS.md sync convention.
Frontmatter descriptions untouched, so skill firing is unchanged.
Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The tcl-whatis and tcl-nslist skill descriptions contained ': ' mid-string,
which is illegal in a plain YAML scalar and broke frontmatter parsing in
strict harnesses. Wrap both description values in double quotes (all four
copies: .agents/skills and .claude/skills).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The skills existed but sessions never leaned on them - grep+read wins
the tool-selection contest when descriptions are phrased as information
needs ("use when you need to know how to call...") rather than task
triggers, and grep 'succeeds' without revealing which of the repo's
coexisting module copies is loaded. Changes to convert them from
available options into workflow steps:
- SKILL.md descriptions rewritten task-first ("Use BEFORE reviewing,
testing, editing..." / "Use BEFORE writing any new Tcl helper..."),
with run-it-first wording, the multiple-module-copies rationale, and
cost stated up front (one sub-1s side-effect-free invocation).
- Invocations shortened to lib: script-path form (verified working,
~0.45s each): punk91 src script lib:developer/whatis|nslist.
- New caveat in both: prefer the Bash tool over PowerShell (attached
console can flip colour/terminal detection in punkshell children).
- AGENTS.md Repo-wide Notes entry converted from reference note to
DIRECTIVE: whatis/nslist first, grep reserved for full-text searches.
- .claude/settings.json: allow entries for both scripts (Bash +
PowerShell, punk91/bin/punk91/./bin/punk91 prefixes) so first use is
prompt-free.
.claude/skills copies re-synced from canonical .agents/skills
(diff-verified byte-identical).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
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
Julian Noble