punkshell/goals/G-097-bin-utility-naming-sweep.md

G-097 bin utility naming sweep: punk- prefix for remaining punkshell-own tools

Status: proposed Scope: src/scriptapps/ + src/scriptapps/bin/ (bits, runtime, tclargs scriptset renames; selfsign experiment scripts), bin/ (regenerated wrapper twins + renamed experiment scripts, old names retired), src/tests/modules/punk/mix/testsuites/scriptwrap/ + src/tests/shell/testsuites/binscripts/ (roundtrip pins), bin/AGENTS.md + referencing docs Goal: the punkshell-own bin utilities beyond getzig - the bits, runtime and tclargs scriptsets and the selfsign experiment scripts - carry the punk- prefix per the naming policy recorded in bin/AGENTS.md (G-096), so a user who adds /bin to their PATH gets collision-resistant names, while external-tool wrappers (dtplite, sdx, kettle) and getpunk stay unprefixed. Acceptance: bin/ presents punk-bits, punk-runtime and punk-tclargs (wrapper twins where the polyglot system emits them) and punk- prefixed selfsign experiment scripts, with the old names removed; scriptset sources and _wrap.toml configs are renamed to match; the byte-roundtrip pins (scriptwrap multishell runtime roundtrip, binscripts suites as affected) and every doc/script reference to the old names are updated with the affected test suites passing; no behaviour changes ride along with the renames.

Context

Utilities in bin/ are on a plausible user PATH ("/bin"), so generic names like bits, runtime and tclargs are collidable. User decision 2026-07-20 (recorded with the policy statement in G-096): punkshell-own utilities take a punk- prefix; wrappers for external tools (dtplite, sdx, kettle) stay unprefixed, as does getpunk (already specific, intended future cross-platform entry point). getzig itself is renamed within G-096; this goal sweeps the remainder at a suitable time (user 2026-07-20: the renames "can wait").

Current inventory (2026-07-20): bits and tclargs are wrapped scriptsets (sources in src/scriptapps/, e.g. bits.pl/bits.ps1/bits.sh + bits_wrap.toml; outputs bin/bits.cmd + twins), runtime's scriptset lives in src/scriptapps/bin/ (bin/runtime.cmd pinned byte-for-byte by the scriptwrap multishell roundtrip test; bin/AGENTS.md carries its fetch/selection contract), and the selfsign material is loose experiment scripts (bin/selfsign.ps1, selfsign1.ps1, selfsign_test1.{bat,ps1}, create-localmachine-selfsigned-cert.ps1 + exported cert).

Notes

• bits background (user 2026-07-20): Windows Sandbox experiments for starting things on a clean machine. Windows Sandbox differs from a true fresh windows install but remains a reasonable initialization proving ground if automatable; qemu may be the better target for full cross-platform testing (G-060). bits is kept regardless of sweep timing.
• selfsign experiments likewise kept (user 2026-07-20); rename only, no productization implied by this goal.
• runtime.cmd has the widest blast radius: the scriptwrap roundtrip pin (src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test scriptwrap_runtime_cmd_roundtrip_no_drift), the bin/AGENTS.md runtime fetch/selection contract section, and runbook references - all updated as part of the rename.
• Related goals: G-096 (policy home + getzig rename), G-060 (qemu test matrix), G-089 (scriptlib/kit deployment surface).